effect-motion 0.4.0 → 0.5.0

package/dist/Entity.js

@@ -1,29 +1,273 @@
+import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-export const TypeId = "~motion/Entity";
-/** the entity's trait lens, or a defect naming entity and trait */
-export const traitOrDie = (entity, key) => {
-    const lens = entity.traits[key];
-    if (lens === undefined) {
-        throw new Error(`Entity "${entity.name}" does not implement the "${key}" trait`);
-    }
-    return lens;
-};
-const normalizeStructLike = (data) => {
-    return (Schema.isSchema(data) ? data : Schema.Struct(data));
-};
-export const make = (name, data, traits) => {
-    const normalized = normalizeStructLike(data);
-    // `$` is reserved for builtin, engine-owned instance properties (e.g.
-    // `$visible`), which live beside the data — never as entity-data fields.
-    for (const field of Object.keys(normalized.fields)) {
-        if (field.startsWith("$")) {
-            throw new Error(`Entity "${name}": field "${field}" uses the reserved "$" prefix (reserved for builtin instance properties like $visible)`);
-        }
-    }
-    return {
-        [TypeId]: TypeId,
-        name,
-        data: normalized,
-        traits: traits ?? {},
-    };
+import * as Color from "./Color.js";
+import * as Font from "./Font.js";
+import * as ImageResource from "./Image.js";
+/**
+ * The closed entity world.
+ *
+ * Every entity the library knows is a member of one tagged union, declared
+ * here. There is deliberately no way to define an entity outside this module:
+ * an entity's complete field set is derivable from its `_tag` alone, which
+ * is what lets the runner, the animators, and the renderer narrow instead
+ * of casting.
+ *
+ * Shared fields come from mixins, never from per-entity declarations, so no
+ * entity can quietly omit or rename one. An `Instance` is a REFERENCE to a
+ * live entity in the runner tree — see `Instance.ts`.
+ */
+/**
+ * A point or offset in 3D space.
+ *
+ * @remarks
+ * Scene coordinates with depth: `x` right, `y` UP (the mathematical
+ * convention), `z` toward the viewer, origin at the viewport center — a
+ * right-handed frame. Every axis defaults to 0, so `vec3({ x: 100 })` is a
+ * valid horizontal offset.
+ *
+ * At `z = 0` content renders exactly as flat 2D. Non-zero `z` is only
+ * meaningful under a perspective camera, where it changes apparent size and
+ * parallax.
+ */
+export const Vec3 = Schema.TaggedStruct("Vec3", {
+    x: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+    y: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+    z: Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(0))),
+});
+/**
+ * Build a {@link Vec3}; omitted axes are 0.
+ *
+ * @example
+ * ```typescript
+ * Entity.vec3({ x: 100, y: 50 })
+ * ```
+ */
+export const vec3 = Vec3.make;
+const vec3Default = (x, y, z) => Vec3.pipe(Schema.withConstructorDefault(Effect.sync(() => Vec3.make({ x, y, z }))));
+const defaultedNumber = (value) => Schema.Number.pipe(Schema.withConstructorDefault(Effect.succeed(value)));
+/**
+ * Position and orientation. Carried by EVERY entity, the camera included:
+ * a viewpoint has a location and an orientation like anything else.
+ */
+const transformMixin = {
+    position: vec3Default(0, 0, 0),
+    rotation: vec3Default(0, 0, 0),
 };
+/**
+ * Presentation state for things that PAINT. The camera is the one entity
+ * that does not (it is view state, omitted from the frame's instance map),
+ * so it takes the transform mixin and none of this.
+ */
+const appearanceMixin = {
+    scale: vec3Default(1, 1, 1),
+    opacity: defaultedNumber(1),
+    visible: Schema.Boolean.pipe(Schema.withConstructorDefault(Effect.succeed(true))),
+};
+/** transform + appearance: the base every paintable entity shares */
+const paintableMixin = {
+    ...transformMixin,
+    ...appearanceMixin,
+};
+const strokeMixin = {
+    strokeWidth: defaultedNumber(1),
+    strokeColor: Color.Color.pipe(Schema.withConstructorDefault(Effect.succeed(Color.black))),
+};
+const fillMixin = {
+    fillColor: Color.Color.pipe(Schema.withConstructorDefault(Effect.succeed(Color.white))),
+};
+/**
+ * Children are stored as instance ids, in paint order. The AUTHORING input
+ * is more permissive (a string becomes a Text, an Instance contributes its
+ * id, an un-yielded `instantiate` effect is resolved) — the runner
+ * normalizes it here, so stored data stays plain ids.
+ */
+const childrenMixin = {
+    children: Schema.Array(Schema.String).pipe(Schema.withConstructorDefault(Effect.sync(() => []))),
+};
+/**
+ * A path command point, relative to the Path's own `position` — the same
+ * relative rule Line's endpoints follow, so translating a Path is rigid
+ * without rewriting the command array.
+ */
+const point = {
+    x: Schema.Number,
+    y: Schema.Number,
+    z: Schema.optionalKey(Schema.Number),
+};
+export const PathCommand = Schema.TaggedUnion({
+    M: point,
+    L: point,
+    Z: {},
+});
+// ── the entities ─────────────────────────────────────────────────────────
+/**
+ * A segment. `start`/`end` are offsets from `position`, so moving the line
+ * translates it rigidly — no endpoint compensation anywhere in the system.
+ * Skeletal: parametrized by its endpoints, never by an anchor plus size.
+ */
+export const Line = Schema.TaggedStruct("Line", {
+    ...paintableMixin,
+    ...strokeMixin,
+    start: vec3Default(0, 0, 0),
+    end: vec3Default(0, 0, 0),
+});
+/**
+ * A polyline/polygon. Command points are relative to `position` (see
+ * `point`). The first command must be `M` — an open vocabulary of M/L/Z;
+ * curves and arcs arrive later via deterministic flattening.
+ */
+export const Path = Schema.TaggedStruct("Path", {
+    ...paintableMixin,
+    ...fillMixin,
+    ...strokeMixin,
+    commands: Schema.NonEmptyArray(PathCommand).check(Schema.makeFilter((commands) => commands[0]._tag === "M"
+        ? undefined
+        : { path: [0], issue: "the first path command must be M" })),
+});
+/**
+ * The canonical 2.5D plane. All-zero rotation is a camera-facing billboard;
+ * non-zero tilts it as a real plane in 3D.
+ */
+export const Rect = Schema.TaggedStruct("Rect", {
+    ...paintableMixin,
+    ...fillMixin,
+    ...strokeMixin,
+    width: defaultedNumber(100),
+    height: defaultedNumber(100),
+});
+/** A filled circle of a given `radius`, centered on its `position`. */
+export const Circle = Schema.TaggedStruct("Circle", {
+    ...paintableMixin,
+    ...fillMixin,
+    ...strokeMixin,
+    radius: defaultedNumber(10),
+});
+/** An ellipse with independent `radiusX` and `radiusY`. */
+export const Ellipse = Schema.TaggedStruct("Ellipse", {
+    ...paintableMixin,
+    ...fillMixin,
+    ...strokeMixin,
+    radiusX: defaultedNumber(20),
+    radiusY: defaultedNumber(10),
+});
+/**
+ * A plain-string text leaf. The engine cannot measure text, so `text` has
+ * no dimensional fields — layout is the renderer's business. Inline
+ * formatting is expressed by composing several Texts, not by a rich tree.
+ */
+export const Text = Schema.TaggedStruct("Text", {
+    ...paintableMixin,
+    ...fillMixin,
+    text: Schema.String,
+    // numeric, therefore tweenable
+    fontSize: defaultedNumber(16),
+    // a Font resource reference ({_tag, id}), never a bare string. Defaults
+    // to the built-in font, so bare Text stays zero-ceremony and the default
+    // never enters the scene's loader requirements.
+    fontFamily: Font.schema.pipe(Schema.withConstructorDefault(Effect.sync(() => Font.schema.make({ id: Font.defaultFont.id })))),
+    textAnchor: Schema.optionalKey(Schema.Literals(["start", "middle", "end"])),
+    baseline: Schema.optionalKey(Schema.Literals(["auto", "middle", "hanging"])),
+});
+/**
+ * A container: positions and structures its children, paints nothing
+ * itself. Its transform composes down the subtree like any entity's.
+ *
+ * It carries no composition bounds. `width`/`height`/`backgroundColor` used
+ * to live here so `Scene.play` could copy a nested scene's dimensions onto
+ * the mount group; a Scene owns those itself, and a render-to-texture
+ * boundary is `Scene.play`'s business, not a field on every group.
+ */
+export const Group = Schema.TaggedStruct("Group", {
+    ...paintableMixin,
+    ...childrenMixin,
+});
+/**
+ * A screen-space container: its subtree is projected through the identity
+ * camera rather than the active one, so HUD content ignores camera
+ * movement, zoom, and shake, and always paints on top.
+ *
+ * `position.z` is depth WITHIN the HUD tier — z consistently means depth in
+ * the entity's own coordinate space, world for world content and screen for
+ * HUD content. A Hud must be a top-level child of the root (or of another
+ * Hud); nesting one inside world content is a loud defect.
+ */
+export const Hud = Schema.TaggedStruct("Hud", {
+    ...paintableMixin,
+    ...childrenMixin,
+});
+/**
+ * A raster/vector image leaf. `image` is an Image resource reference; the
+ * bytes live in the scene's requirements, never in frame data.
+ *
+ * `width`/`height` are optional and undefaulted: set BOTH to draw at that
+ * size (numeric, so they tween), leave both absent for the source's natural
+ * size. A lone dimension is ignored — aspect math needs the natural size,
+ * which frame data never sees.
+ */
+export const Image = Schema.TaggedStruct("Image", {
+    ...paintableMixin,
+    image: ImageResource.schema,
+    width: Schema.optionalKey(Schema.Number),
+    height: Schema.optionalKey(Schema.Number),
+});
+/**
+ * The viewpoint — the one entity that is never drawn.
+ *
+ * @remarks
+ * A camera is view state rather than content, so it carries `position` and
+ * `rotation` but no `scale`, `opacity`, or `visible`, and is absent from the
+ * frame's instance map. Every scene has one already; reach for it with
+ * `Scene.camera`.
+ *
+ * `focalLength` sets the perspective strength — a longer lens flattens
+ * depth, a shorter one exaggerates it. It and the resting `z` are
+ * width-relative and filled in by the runner at instantiate time (only the
+ * runner knows the composition width), so the zero defaults here are
+ * placeholders that are always overwritten. The resting values are chosen so
+ * content at `z = 0` renders exactly as flat 2D.
+ *
+ * `poi` is an optional point of interest: when set, the camera auto-aims at
+ * that world point and any explicit `rotation` composes on top of the aim.
+ * The `Camera` module's helpers are the ergonomic way to drive it.
+ *
+ * `aperture` and `focusDistance` describe depth of field. They are carried
+ * on the frame but currently have NO visual effect — depth-of-field
+ * rendering is not implemented, and every frame renders sharp.
+ */
+export const Camera = Schema.TaggedStruct("Camera", {
+    ...transformMixin,
+    focalLength: defaultedNumber(0),
+    focusDistance: defaultedNumber(0),
+    aperture: defaultedNumber(0),
+    poi: Vec3.pipe(Schema.NullOr, Schema.withConstructorDefault(Effect.succeed(null))),
+});
+// ── the union ────────────────────────────────────────────────────────────
+export const EntityMap = {
+    Line,
+    Path,
+    Rect,
+    Circle,
+    Ellipse,
+    Text,
+    Group,
+    Hud,
+    Image,
+    Camera,
+};
+export const getEntityDefinitionByTag = (tag) => EntityMap[tag];
+/**
+ * Every container tag, exhaustively. `Record<ContainerTag, true>` (not
+ * `satisfies Array<ContainerTag>`) is deliberate: an array only checks its
+ * members are valid tags, so a newly-added container would silently miss
+ * this set. A Record demands every key, so omitting one fails the build.
+ */
+const containerTags = {
+    Group: true,
+    Hud: true,
+};
+/**
+ * Whether an entity can hold children. Previously this was "does its data
+ * have a `children` field", answerable only at runtime because entity shapes
+ * were unknowable; now it is a property of the tag.
+ */
+export const isContainer = (entity) => entity._tag in containerTags;

package/dist/Font.d.ts

@@ -0,0 +1,108 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Resource from "./Resource.js";
+import type { EnsureLiteral } from "./types.js";
+export declare const tag: "effect-motion/Resources/Font";
+/**
+ * A font reference as entity data stores it: `{ _tag, id }`. The id is the
+ * family name text paints register and select by. Obtain one by yielding a
+ * {@link Font} constant inside a scene — that is what puts the matching
+ * `FontLoader<ID>` into the scene's requirements.
+ */
+export interface Font<ID extends string = string> {
+    readonly _tag: typeof tag;
+    readonly id: ID;
+}
+/** The stored-data schema for font references (see `Text.fontFamily`). */
+export declare const schema: Schema.TaggedStruct<"effect-motion/Resources/Font", {
+    readonly id: Schema.String;
+}>;
+/**
+ * A loaded font, provided as a context service: bytes are already in memory
+ * by the time any consumer reads this (loads run eagerly at layer
+ * construction — see {@link layer}). `format` is optional; consumers sniff
+ * magic bytes when absent.
+ */
+export interface FontLoader<ID extends string = string> extends Resource.LoaderBrand {
+    readonly id: ID;
+    readonly bytes: Uint8Array;
+    readonly format?: "ttf" | "otf";
+}
+/**
+ * The context key for a font's loader, derived from the id string alone —
+ * the bridge over literal erasure: frame data carries only `{ id: string }`,
+ * and rebuilding the key from that string resolves the same service the
+ * authored constant provides.
+ */
+export declare const Loader: <ID extends string>(id: ID) => Context.Service<FontLoader<ID>, FontLoader<ID>>;
+/**
+ * One font constant, two faces:
+ *
+ * - **author side**: `yield*` it in a scene to get the {@link Font} value for
+ *   `fontFamily`, adding `FontLoader<ID>` to the scene's requirements. The
+ *   requirement is PHANTOM — the effect succeeds without touching context,
+ *   so `Scene.run`/`stream` stay loader-free and only the render path
+ *   (the first actual consumer of bytes) demands the loader.
+ * - **provider side**: `.Loader` is the context key; pair it with
+ *   {@link layer} to provide bytes.
+ */
+export interface FontResource<ID extends string = string> extends Effect.Effect<Font<ID>, never, FontLoader<ID>> {
+    readonly id: ID;
+    readonly Loader: Context.Service<FontLoader<ID>, FontLoader<ID>>;
+}
+/**
+ * Declare a font your scene uses.
+ *
+ * @remarks
+ * Call it once at module scope to get a constant with two faces: `yield*` it
+ * inside a scene to obtain the value for a Text's `fontFamily`, and pair it
+ * with {@link layer} to supply the actual bytes when rendering.
+ *
+ * Yielding the constant is what records the font in the scene's
+ * requirements, so a scene that uses a font it was never given fails to
+ * typecheck instead of rendering in the wrong face.
+ *
+ * The id must be a literal string — that literal is what ties the
+ * requirement to the provider.
+ *
+ * @param id - The family name, as a literal string.
+ *
+ * @example
+ * ```typescript
+ * const Inter = Font.Font("Inter");
+ *
+ * const scene = Scene.make(function* () {
+ * 	const inter = yield* Inter;
+ * 	yield* Scene.instantiate("Text", { text: "hello", fontFamily: inter });
+ * });
+ * ```
+ */
+export declare const Font: <const ID extends string>(id: ID & EnsureLiteral<ID, "Font id must be a literal string">) => FontResource<ID>;
+/**
+ * Provide a font's bytes. The load effect runs ONCE, at layer construction
+ * (runtime build) — never at frame time; compose retries/timeouts on the
+ * load effect itself. Every provided font loads regardless of whether the
+ * scene ends up using it (preload-all-provided policy).
+ */
+export declare const layer: <ID extends string, E, R>(font: FontResource<ID>, load: Effect.Effect<Uint8Array, E, R>, options?: {
+    readonly format?: "ttf" | "otf";
+}) => Layer.Layer<FontLoader<ID>, E, R>;
+/**
+ * The built-in default font under the RESERVED id `"sans-serif"` — the
+ * `Text.fontFamily` constructor default. It never appears in a scene's
+ * requirements (no `yield*` happens for a schema default); the render path
+ * auto-provides its loader beneath caller context, so providing your own
+ * loader under the `"sans-serif"` id overrides the built-in bytes.
+ */
+export declare const defaultFont: FontResource<"sans-serif">;
+export { defaultFont as default };
+/**
+ * A CORS-open, static-weight TrueType mapped to the default family. Lived
+ * on the render engine before this refactor; now the render path fetches it
+ * (module-cached) only when a frame actually uses the default font and no
+ * caller-provided `"sans-serif"` loader is in context.
+ */
+export declare const DEFAULT_FONT_URL = "https://cdn.jsdelivr.net/npm/@expo-google-fonts/inter@0.2.3/Inter_400Regular.ttf";
+export declare const loadDefaultBytes: Effect.Effect<Uint8Array>;

package/dist/Font.js

@@ -0,0 +1,95 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Resource from "./Resource.js";
+export const tag = "effect-motion/Resources/Font";
+/** The stored-data schema for font references (see `Text.fontFamily`). */
+export const schema = Schema.TaggedStruct(tag, {
+    id: Schema.String,
+});
+const loaderKeyPrefix = "effect-motion/Resources/FontLoader/";
+/**
+ * The context key for a font's loader, derived from the id string alone —
+ * the bridge over literal erasure: frame data carries only `{ id: string }`,
+ * and rebuilding the key from that string resolves the same service the
+ * authored constant provides.
+ */
+export const Loader = (id) => Context.Service(`${loaderKeyPrefix}${id}`);
+/**
+ * Declare a font your scene uses.
+ *
+ * @remarks
+ * Call it once at module scope to get a constant with two faces: `yield*` it
+ * inside a scene to obtain the value for a Text's `fontFamily`, and pair it
+ * with {@link layer} to supply the actual bytes when rendering.
+ *
+ * Yielding the constant is what records the font in the scene's
+ * requirements, so a scene that uses a font it was never given fails to
+ * typecheck instead of rendering in the wrong face.
+ *
+ * The id must be a literal string — that literal is what ties the
+ * requirement to the provider.
+ *
+ * @param id - The family name, as a literal string.
+ *
+ * @example
+ * ```typescript
+ * const Inter = Font.Font("Inter");
+ *
+ * const scene = Scene.make(function* () {
+ * 	const inter = yield* Inter;
+ * 	yield* Scene.instantiate("Text", { text: "hello", fontFamily: inter });
+ * });
+ * ```
+ */
+export const Font = (id) => {
+    const value = { _tag: tag, id };
+    // R is covariant, so the loader-free succeed widens to the phantom
+    // FontLoader<ID> requirement without a cast
+    return Object.assign(Effect.succeed(value), {
+        id: id,
+        Loader: Loader(id),
+    });
+};
+/**
+ * Provide a font's bytes. The load effect runs ONCE, at layer construction
+ * (runtime build) — never at frame time; compose retries/timeouts on the
+ * load effect itself. Every provided font loads regardless of whether the
+ * scene ends up using it (preload-all-provided policy).
+ */
+export const layer = (font, load, options) => Layer.effect(font.Loader, load.pipe(Effect.map((bytes) => ({
+    [Resource.LoaderTypeId]: Resource.LoaderTypeId,
+    id: font.id,
+    bytes,
+    ...(options?.format !== undefined ? { format: options.format } : {}),
+}))));
+/**
+ * The built-in default font under the RESERVED id `"sans-serif"` — the
+ * `Text.fontFamily` constructor default. It never appears in a scene's
+ * requirements (no `yield*` happens for a schema default); the render path
+ * auto-provides its loader beneath caller context, so providing your own
+ * loader under the `"sans-serif"` id overrides the built-in bytes.
+ */
+export const defaultFont = Font("sans-serif");
+export { defaultFont as default };
+/**
+ * A CORS-open, static-weight TrueType mapped to the default family. Lived
+ * on the render engine before this refactor; now the render path fetches it
+ * (module-cached) only when a frame actually uses the default font and no
+ * caller-provided `"sans-serif"` loader is in context.
+ */
+export const DEFAULT_FONT_URL = "https://cdn.jsdelivr.net/npm/@expo-google-fonts/inter@0.2.3/Inter_400Regular.ttf";
+// immutable bytes, fetched at most once per process — the default font must
+// not refetch per render call
+let defaultBytesCache;
+export const loadDefaultBytes = Effect.promise(() => {
+    defaultBytesCache ??= fetch(DEFAULT_FONT_URL).then(async (response) => {
+        if (!response.ok) {
+            defaultBytesCache = undefined;
+            throw new Error(`default font fetch failed (HTTP ${response.status}): ${DEFAULT_FONT_URL}`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    });
+    return defaultBytesCache;
+});

package/dist/Image.d.ts

@@ -0,0 +1,71 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Resource from "./Resource.js";
+import type { EnsureLiteral } from "./types.js";
+export declare const tag: "effect-motion/Resources/Image";
+/**
+ * An image reference as entity data stores it: `{ _tag, id }`. Obtain one
+ * by yielding an {@link Image} constant inside a scene — that is what puts
+ * the matching `ImageLoader<ID>` into the scene's requirements.
+ */
+export interface Image<ID extends string = string> {
+    readonly _tag: typeof tag;
+    readonly id: ID;
+}
+/** The stored-data schema for image references (see `Shapes.Image`). */
+export declare const schema: Schema.TaggedStruct<"effect-motion/Resources/Image", {
+    readonly id: Schema.String;
+}>;
+/**
+ * A loaded image (encoded bytes — png/jpg/webp per the render session's
+ * decoder), provided as a context service: bytes are already in memory by
+ * the time any consumer reads this (loads run eagerly at layer
+ * construction — see {@link layer}). A separate shape from FontLoader on
+ * purpose (kind-specific metadata will diverge); only the loader brand is
+ * shared.
+ */
+export interface ImageLoader<ID extends string = string> extends Resource.LoaderBrand {
+    readonly id: ID;
+    readonly bytes: Uint8Array;
+}
+/** The context key for an image's loader, derived from the id string alone. */
+export declare const Loader: <ID extends string>(id: ID) => Context.Service<ImageLoader<ID>, ImageLoader<ID>>;
+/**
+ * One image constant, two faces — author side (`yield*` for the value and
+ * the phantom `ImageLoader<ID>` requirement) and provider side (`.Loader`
+ * plus {@link layer}). See `Font.Font` for the full contract; images follow
+ * it exactly.
+ */
+export interface ImageResource<ID extends string = string> extends Effect.Effect<Image<ID>, never, ImageLoader<ID>> {
+    readonly id: ID;
+    readonly Loader: Context.Service<ImageLoader<ID>, ImageLoader<ID>>;
+}
+/**
+ * Declare an image your scene uses.
+ *
+ * @remarks
+ * Follows the same two-faced contract as `Font.Font`: `yield*` the constant
+ * in a scene to get the reference for an Image entity, and pair it with
+ * {@link layer} to provide the encoded bytes. Yielding is what puts the
+ * requirement into the scene's type.
+ *
+ * @param id - An identifier for this image, as a literal string.
+ *
+ * @example
+ * ```typescript
+ * const Logo = Image.Image("logo");
+ *
+ * const scene = Scene.make(function* () {
+ * 	const logo = yield* Logo;
+ * 	yield* Scene.instantiate("Image", { image: logo, width: 200, height: 80 });
+ * });
+ * ```
+ */
+export declare const Image: <const ID extends string>(id: ID & EnsureLiteral<ID, "Image id must be a literal string">) => ImageResource<ID>;
+/**
+ * Provide an image's encoded bytes. The load effect runs ONCE, at layer
+ * construction — never at frame time; compose retries on the load effect.
+ */
+export declare const layer: <ID extends string, E, R>(image: ImageResource<ID>, load: Effect.Effect<Uint8Array, E, R>) => Layer.Layer<ImageLoader<ID>, E, R>;

package/dist/Image.js

@@ -0,0 +1,50 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Resource from "./Resource.js";
+export const tag = "effect-motion/Resources/Image";
+/** The stored-data schema for image references (see `Shapes.Image`). */
+export const schema = Schema.TaggedStruct(tag, {
+    id: Schema.String,
+});
+const loaderKeyPrefix = "effect-motion/Resources/ImageLoader/";
+/** The context key for an image's loader, derived from the id string alone. */
+export const Loader = (id) => Context.Service(`${loaderKeyPrefix}${id}`);
+/**
+ * Declare an image your scene uses.
+ *
+ * @remarks
+ * Follows the same two-faced contract as `Font.Font`: `yield*` the constant
+ * in a scene to get the reference for an Image entity, and pair it with
+ * {@link layer} to provide the encoded bytes. Yielding is what puts the
+ * requirement into the scene's type.
+ *
+ * @param id - An identifier for this image, as a literal string.
+ *
+ * @example
+ * ```typescript
+ * const Logo = Image.Image("logo");
+ *
+ * const scene = Scene.make(function* () {
+ * 	const logo = yield* Logo;
+ * 	yield* Scene.instantiate("Image", { image: logo, width: 200, height: 80 });
+ * });
+ * ```
+ */
+export const Image = (id) => {
+    const value = { _tag: tag, id };
+    return Object.assign(Effect.succeed(value), {
+        id: id,
+        Loader: Loader(id),
+    });
+};
+/**
+ * Provide an image's encoded bytes. The load effect runs ONCE, at layer
+ * construction — never at frame time; compose retries on the load effect.
+ */
+export const layer = (image, load) => Layer.effect(image.Loader, load.pipe(Effect.map((bytes) => ({
+    [Resource.LoaderTypeId]: Resource.LoaderTypeId,
+    id: image.id,
+    bytes,
+}))));