@fungi.computer/sprite 0.0.0-stage → 0.0.1

package/dist/player.js

@@ -0,0 +1,368 @@
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as z from "zod";
+import { createAssetReader } from "./assets.js";
+import { resolveAppearance } from "./controls.js";
+import { createRenderStyleLayer, renderStyleSchema, } from "./render-style.js";
+import { characterSchema, localCharacterSourceSchema, } from "./document.js";
+const resolveSource = (source, baseURL) => {
+    const local = localCharacterSourceSchema.safeParse(source);
+    if (local.success)
+        return { kind: "local", key: local.data.local };
+    return {
+        kind: "remote",
+        url: new URL(z.string().parse(source), baseURL).href,
+    };
+};
+const asError = (cause) => cause instanceof Error ? cause : new Error(String(cause), { cause });
+const exitError = (exit) => Exit.isFailure(exit)
+    ? asError(Cause.squash(exit.cause))
+    : new Error("Unexpected Sprite success");
+/** Stable shell service; each mounted player owns its own selection. */
+export function createSprite(options) {
+    const maxPixels = options.maxPixels ?? 4_194_304;
+    if (!Number.isSafeInteger(maxPixels) || maxPixels <= 0)
+        throw new Error("Sprite pixel limit must be a positive safe integer");
+    const assetPolicy = options.assets ?? {
+        baseURL: "https://sprite.invalid/",
+        allowedOrigins: [],
+        maxBytes: 1,
+        maxTotalBytes: 1,
+        maxRequests: 1,
+    };
+    const newAssetReader = createAssetReader(assetPolicy);
+    const owners = new WeakSet();
+    const priorCleanup = new WeakMap();
+    const sourceKey = (source) => {
+        const resolved = resolveSource(source, assetPolicy.baseURL);
+        return resolved.kind === "remote" ? resolved.url : `local:${resolved.key}`;
+    };
+    return {
+        mount(target) {
+            if (owners.has(target))
+                throw new Error("A Sprite already owns this target");
+            owners.add(target);
+            const mountScope = Effect.runSync(Scope.make());
+            const listeners = new Set();
+            let state = { status: "empty" };
+            let desired;
+            let selection;
+            let revision = 0;
+            let dirty = false;
+            let worker;
+            let retiring;
+            let closing;
+            let disposed = false;
+            let paused = false;
+            const view = target.ownerDocument.defaultView;
+            const motion = view?.matchMedia("(prefers-reduced-motion: reduce)");
+            const publish = (next) => {
+                if (disposed && next.status !== "destroyed")
+                    return;
+                state = next;
+                for (const listener of listeners) {
+                    try {
+                        listener(next);
+                    }
+                    catch (error) {
+                        console.error("Sprite state observer failed", error);
+                    }
+                }
+            };
+            const failSelection = (error) => {
+                selection?.controller.abort();
+                selection?.holder.remove();
+                publish({ status: "error", error });
+                void closeSelection().catch((cleanupError) => {
+                    publish({
+                        status: "error",
+                        error: new AggregateError([error, cleanupError], "Avatar failed and cleanup also failed"),
+                    });
+                });
+            };
+            const styles = createRenderStyleLayer(target);
+            const suspend = () => {
+                const still = paused || target.ownerDocument.hidden || motion?.matches === true;
+                styles.still(still);
+                try {
+                    selection?.native?.pause(still);
+                }
+                catch (error) {
+                    failSelection(asError(error));
+                }
+            };
+            Effect.runSync(Scope.addFinalizer(mountScope, Effect.sync(() => {
+                target.ownerDocument.removeEventListener("visibilitychange", suspend);
+                motion?.removeEventListener("change", suspend);
+                styles.dispose();
+            })));
+            target.ownerDocument.addEventListener("visibilitychange", suspend);
+            motion?.addEventListener("change", suspend);
+            const closeSelection = async () => {
+                if (retiring)
+                    return retiring;
+                const old = selection;
+                if (!old)
+                    return;
+                selection = undefined;
+                old.controller.abort();
+                old.holder.remove();
+                const cleanup = Effect.runPromiseExit(Scope.close(old.scope, Exit.void)).then((exit) => {
+                    if (Exit.isFailure(exit))
+                        throw exitError(exit);
+                });
+                retiring = cleanup;
+                try {
+                    await cleanup;
+                }
+                finally {
+                    if (retiring === cleanup)
+                        retiring = undefined;
+                }
+            };
+            const apply = (current) => {
+                const native = current.native;
+                const document = current.document;
+                const request = desired;
+                if (!native || !document || !request || selection !== current)
+                    return;
+                const activity = request.activity ?? "idle";
+                const expression = request.expression ?? native.expressions[0] ?? null;
+                let appearance;
+                let renderStyle;
+                try {
+                    appearance = resolveAppearance(document.controls, request.appearance);
+                    renderStyle = renderStyleSchema.parse(request.renderStyle ?? "plain");
+                }
+                catch (error) {
+                    const updateError = asError(error);
+                    if (state.status === "ready") {
+                        if (state.updateError?.message !== updateError.message)
+                            publish({ ...state, updateError });
+                    }
+                    else
+                        failSelection(updateError);
+                    return;
+                }
+                const effective = {
+                    requestedActivity: activity,
+                    requestedExpression: expression,
+                    activity: native.activities.includes(activity) ? activity : "idle",
+                    expression: expression !== null && native.expressions.includes(expression)
+                        ? expression
+                        : (native.expressions[0] ?? null),
+                    appearance,
+                    renderStyle,
+                    fallback: !native.activities.includes(activity) ||
+                        (expression !== null && !native.expressions.includes(expression)),
+                };
+                const key = JSON.stringify([
+                    effective.activity,
+                    effective.expression,
+                    effective.appearance,
+                ]);
+                styles.set(renderStyle, current.holder);
+                if (key === current.appliedKey &&
+                    state.status === "ready" &&
+                    state.presentation.renderStyle === renderStyle &&
+                    state.updateError === undefined &&
+                    state.presentation.requestedActivity === activity &&
+                    state.presentation.requestedExpression === expression)
+                    return;
+                try {
+                    if (key !== current.appliedKey)
+                        native.set(effective);
+                    current.appliedKey = key;
+                    suspend();
+                    if (selection === current)
+                        publish({ status: "ready", document, presentation: effective });
+                }
+                catch (error) {
+                    failSelection(asError(error));
+                }
+            };
+            const openSelection = async (request, key, token) => {
+                const readAsset = newAssetReader();
+                const scope = Effect.runSync(Scope.make());
+                const controller = new AbortController();
+                const holder = target.ownerDocument.createElement("div");
+                holder.style.cssText = "width:100%;height:100%;position:relative";
+                const current = { key, scope, controller, holder };
+                selection = current;
+                Effect.runSync(Scope.addFinalizer(scope, Effect.sync(() => {
+                    holder.remove();
+                })));
+                // Canvas engines need a real layout box before native initialization.
+                target.append(holder);
+                const program = Effect.gen(function* () {
+                    let document;
+                    let render;
+                    let base = assetPolicy.baseURL;
+                    const source = resolveSource(request.src, assetPolicy.baseURL);
+                    if (source.kind === "remote") {
+                        const asset = yield* Effect.tryPromise({
+                            try: () => readAsset(source.url, controller.signal),
+                            catch: asError,
+                        });
+                        base = asset.url;
+                        document = characterSchema.parse(JSON.parse(new TextDecoder().decode(asset.bytes)));
+                        const loader = options.renderers &&
+                            Object.hasOwn(options.renderers, document.renderer)
+                            ? options.renderers[document.renderer]
+                            : undefined;
+                        if (!loader)
+                            throw new Error(`Renderer is not installed: ${document.renderer}`);
+                        render = (yield* Effect.tryPromise({ try: loader, catch: asError }))
+                            .default;
+                    }
+                    else {
+                        const local = source.key;
+                        const loader = options.characters && Object.hasOwn(options.characters, local)
+                            ? options.characters[local]
+                            : undefined;
+                        if (!loader)
+                            throw new Error(`Character is not installed: ${local}`);
+                        const character = yield* Effect.tryPromise({
+                            try: loader,
+                            catch: asError,
+                        });
+                        document = characterSchema.parse(character.document);
+                        render = character.render;
+                    }
+                    controller.signal.throwIfAborted();
+                    const assetURL = (reference) => Effect.gen(function* () {
+                        const asset = yield* Effect.tryPromise({
+                            try: () => readAsset(reference, controller.signal, base),
+                            catch: asError,
+                        });
+                        return yield* Effect.acquireRelease(Effect.sync(() => URL.createObjectURL(new Blob([asset.bytes], { type: asset.contentType }))), (url) => Effect.sync(() => {
+                            URL.revokeObjectURL(url);
+                        }));
+                    });
+                    const native = yield* render({
+                        target: holder,
+                        document,
+                        signal: controller.signal,
+                        maxPixels,
+                        reportError: (error) => {
+                            if (selection === current && !controller.signal.aborted)
+                                failSelection(error);
+                        },
+                        assetURL,
+                    });
+                    if (!native.activities.includes("idle"))
+                        throw new Error("Character has no idle fallback");
+                    native.pause(true);
+                    return { native, document };
+                }).pipe(Scope.provide(scope));
+                const exit = await Effect.runPromiseExit(program, {
+                    signal: controller.signal,
+                });
+                if (disposed || token !== revision || selection !== current) {
+                    return;
+                }
+                if (Exit.isFailure(exit)) {
+                    const error = exitError(exit);
+                    try {
+                        await closeSelection();
+                        publish({ status: "error", error });
+                    }
+                    catch (cleanupError) {
+                        publish({
+                            status: "error",
+                            error: new AggregateError([error, cleanupError], "Avatar load and cleanup failed"),
+                        });
+                    }
+                    return;
+                }
+                current.native = exit.value.native;
+                current.document = exit.value.document;
+                apply(current);
+            };
+            const reconcile = async () => {
+                const superseded = (token) => disposed || token !== revision;
+                while (dirty && !disposed) {
+                    dirty = false;
+                    const token = revision;
+                    await closeSelection();
+                    if (superseded(token) || !desired)
+                        continue;
+                    const prior = await priorCleanup.get(target);
+                    if (prior?.kind === "failed")
+                        throw prior.error;
+                    if (superseded(token))
+                        continue;
+                    publish({ status: "loading" });
+                    await openSelection(desired, sourceKey(desired.src), token);
+                }
+            };
+            const schedule = () => {
+                dirty = true;
+                selection?.controller.abort();
+                selection?.holder.remove();
+                if (worker)
+                    return;
+                worker = reconcile()
+                    .catch((error) => {
+                    publish({ status: "error", error: asError(error) });
+                })
+                    .finally(() => {
+                    worker = undefined;
+                    if (dirty && !disposed)
+                        schedule();
+                });
+            };
+            return {
+                get state() {
+                    return state;
+                },
+                subscribe(listener) {
+                    listeners.add(listener);
+                    return () => listeners.delete(listener);
+                },
+                set(next) {
+                    if (disposed)
+                        throw new Error("Sprite is destroyed");
+                    desired = next;
+                    const key = sourceKey(next.src);
+                    if (selection?.key === key && state.status === "ready")
+                        apply(selection);
+                    else if (selection?.key !== key || state.status === "error") {
+                        revision += 1;
+                        schedule();
+                    }
+                },
+                pause(value) {
+                    if (disposed)
+                        throw new Error("Sprite is destroyed");
+                    paused = value;
+                    suspend();
+                },
+                dispose() {
+                    if (closing)
+                        return closing;
+                    disposed = true;
+                    revision += 1;
+                    owners.delete(target);
+                    selection?.controller.abort();
+                    selection?.holder.remove();
+                    publish({ status: "destroyed" });
+                    closing = (async () => {
+                        await worker;
+                        await closeSelection();
+                        const exit = await Effect.runPromiseExit(Scope.close(mountScope, Exit.void));
+                        if (Exit.isFailure(exit))
+                            throw exitError(exit);
+                    })();
+                    priorCleanup.set(target, closing.then(() => ({ kind: "closed" }), (cause) => ({
+                        kind: "failed",
+                        error: asError(cause),
+                    })));
+                    return closing;
+                },
+            };
+        },
+    };
+}

package/dist/react.d.ts

@@ -0,0 +1,23 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import type { AvatarPresentation, PlayerState, SpriteService } from "./player.js";
+/** Shell-owned renderer and asset configuration; no selected identity lives here. */
+export declare function SpriteProvider({ service, children, }: {
+    readonly service: SpriteService;
+    readonly children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** Avatar presentation plus ordinary attributes for the DOM host. */
+export type SpriteProps = AvatarPresentation & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Optional for standalone use; a shell normally supplies SpriteProvider. */
+    readonly service?: SpriteService;
+    readonly paused?: boolean;
+    /** Observe loading, ready, error, and disposal changes. */
+    readonly onState?: (state: PlayerState) => void;
+};
+/** Own one player; source and appearance changes do not remount its React host. */
+export declare const Sprite: import("react").ForwardRefExoticComponent<AvatarPresentation & Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Optional for standalone use; a shell normally supplies SpriteProvider. */
+    readonly service?: SpriteService;
+    readonly paused?: boolean;
+    /** Observe loading, ready, error, and disposal changes. */
+    readonly onState?: (state: PlayerState) => void;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/react.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, forwardRef, useContext, useEffect, useImperativeHandle, useRef, } from "react";
+/** Renderer-neutral React presentation. The configured service belongs to the shell. */
+const SpriteContext = createContext(null);
+/** Shell-owned renderer and asset configuration; no selected identity lives here. */
+export function SpriteProvider({ service, children, }) {
+    return (_jsx(SpriteContext.Provider, { value: service, children: children }));
+}
+/** Own one player; source and appearance changes do not remount its React host. */
+export const Sprite = forwardRef(function Sprite({ service, src, activity, expression, appearance, renderStyle, paused = false, onState, ...props }, forwardedRef) {
+    const configured = useContext(SpriteContext);
+    const runtime = service ?? configured;
+    if (!runtime)
+        throw new Error("Sprite needs a configured SpriteProvider or service");
+    const host = useRef(null);
+    const player = useRef(null);
+    const notify = useRef(onState);
+    notify.current = onState;
+    useImperativeHandle(forwardedRef, () => {
+        if (!host.current)
+            throw new Error("Sprite host is not mounted");
+        return host.current;
+    });
+    useEffect(() => {
+        if (!host.current)
+            return;
+        const mounted = runtime.mount(host.current);
+        const unsubscribe = mounted.subscribe((state) => {
+            if (host.current)
+                host.current.dataset.spriteStatus = state.status;
+            notify.current?.(state);
+        });
+        player.current = mounted;
+        return () => {
+            unsubscribe();
+            void mounted.dispose().catch((error) => {
+                console.error("Sprite cleanup failed", error);
+            });
+            player.current = null;
+        };
+    }, [runtime]);
+    useEffect(() => {
+        const mounted = player.current;
+        if (!mounted)
+            return;
+        let presentation = { src };
+        if (activity !== undefined)
+            presentation = { ...presentation, activity };
+        if (expression !== undefined)
+            presentation = { ...presentation, expression };
+        if (appearance !== undefined)
+            presentation = { ...presentation, appearance };
+        if (renderStyle !== undefined)
+            presentation = { ...presentation, renderStyle };
+        mounted.set(presentation);
+    }, [runtime, src, activity, expression, appearance, renderStyle]);
+    useEffect(() => {
+        player.current?.pause(paused);
+    }, [runtime, paused]);
+    return _jsx("div", { ...props, ref: host });
+});

package/dist/render-style.d.ts

@@ -0,0 +1,45 @@
+import * as z from "zod";
+/**
+ * Render styles: an SVG filter drawn over a mounted Sprite. This module owns
+ * the style vocabulary, every filter definition, and the DOM layer that mounts
+ * one filter per player with ids unique to that player.
+ */
+export declare const renderStyles: readonly ["plain", "pencil", "manga", "riso", "halftone", "blueprint", "crt", "watercolor"];
+/** A saved render style; unknown names fail at the boundary. */
+export declare const renderStyleSchema: z.ZodEnum<{
+    plain: "plain";
+    pencil: "pencil";
+    manga: "manga";
+    riso: "riso";
+    halftone: "halftone";
+    blueprint: "blueprint";
+    crt: "crt";
+    watercolor: "watercolor";
+}>;
+/** How a Sprite is drawn over its native renderer. */
+export type RenderStyle = z.infer<typeof renderStyleSchema>;
+/** Picker labels for each style, in display order. */
+export declare const renderStyleLabels: {
+    readonly plain: "Plain";
+    readonly pencil: "Pencil";
+    readonly manga: "Manga";
+    readonly riso: "Riso";
+    readonly halftone: "Halftone";
+    readonly blueprint: "Blueprint";
+    readonly crt: "CRT";
+    readonly watercolor: "Watercolor";
+};
+/** The filter layer owned by one mounted player. */
+export type RenderStyleLayer = {
+    /** Draw `stage` in `style`; `plain` removes the filter. */
+    set(style: RenderStyle, stage: HTMLElement): void;
+    /** Hold one still frame: paused, hidden, or reduced motion. */
+    still(value: boolean): void;
+    /** Stop the boil and remove the filter and its definitions. */
+    dispose(): void;
+};
+/**
+ * Mount a render-style layer in `host`. The filter applies only to the stage
+ * box, and its boil runs only while the host is on screen and not still.
+ */
+export declare function createRenderStyleLayer(host: HTMLElement): RenderStyleLayer;