@lute-lang/player-web 0.0.0-stage → 0.41.0

package/README.md

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# @lute-lang/player-web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Lute 0.41 browser visual-novel player. It supplies PixiJS 8 rendering, Web Audio, screens, and keyboard/mouse/touch/gamepad input for the renderer-free `@lute-lang/player` core.
+
+## Install
+
+```sh
+bun add @lute-lang/player-web@0.41.0 @lute-lang/player@0.41.0 @lute-lang/runtime@0.41.0 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
+# npm install @lute-lang/player-web@0.41.0 @lute-lang/player@0.41.0 @lute-lang/runtime@0.41.0 effect@4.0.2 @effect/platform-browser@4.0.2 pixi.js@8.22.0 @pixi/sound@6.0.1
+```
+
+The package requires exact `effect@4.0.2` and `@effect/platform-browser@4.0.2` peers. Runtime and player packages are released in lockstep.
+
+## Minimal usage
+
+Serve a `lute compile --all` bundle, the runtime wasm file, the bindings file, and its assets. Then mount into an element:
+
+```ts
+import { mountPlayer } from "@lute-lang/player-web"
+
+const player = await mountPlayer(document.querySelector("#player")!, {
+  bindings: { url: "/player.bindings.yaml" },
+  bundleUrl: "/bundle/",
+  wasmUrl: "/wasm/lute_runtime_wasm_bg.wasm",
+  assetsUrl: "/assets/",
+  storageKey: "my-game"
+})
+
+await player.act({ type: "newGame" })
+const view = await player.view()
+// Later:
+await player.unmount()
+```
+
+`bindings` accepts a decoded `Bindings` object, YAML text, or `{ url }`. `assetsUrl` overrides the file's `assetsBase`; `host` is the core's `PlayerHost`: `bridge` handlers return a `BridgeAnswer` (`{ fields, writes? }`), `plugin` handlers run as waiting cues, and `idle` answers idle waits. `mountPlayer` returns Promise methods `act`, `view`, and `unmount`. The Effect-native `LuteWeb.mount` is available when the application already manages an Effect scope; its handle is the core's `LutePlayerHandle` (`actions`, `view`, `send`, `restore`, `shutdown`, plus the runtime `session` and its `program`).
+
+## Cue handling
+
+- **Names.** The dialogue name plate and backlog rows show `speakerName`, the cast display name from the bundle index (`cast: { id: name }`); name colours stay keyed by the speaker id.
+- **Music.** `PixiAudio` honours `AudioPlay.restart`: `restart: true` plays the file from its start; without it, the music file already playing only changes volume, fading over `fade`, and a different file crossfades.
+- **Custom vfx.** A `StageCue.Vfx` whose `effect.effect` is `"custom"` (a project vfx bound as `{ effect: custom }`, or a vfx type with no binding) has no Pixi effect: the presenter plays nothing and logs `effect.name` once at debug level (`PresenterOptions.debug`, default `console.debug`). Render project effects with your own `Presenter`.
+
+## API and guides
+
+- [Web architecture](../../docs/player/web-architecture.md)
+- [Getting started](/player/getting-started/)
+- [Controls](/player/controls/)
+- [Bindings reference](/player/bindings/)
+- [Demo game](../../examples/player-demo/)
+
+Source and releases: [github.com/journeyWorker/lute](https://github.com/journeyWorker/lute).

package/dist/assets/pixiAssets.d.ts

@@ -0,0 +1,47 @@
+import { Texture } from "pixi.js";
+import { Effect, Scope, Stream } from "effect";
+import { AssetMissing, type AssetLoader } from "@lute-lang/player";
+/** Backend seam for PixiAssets; tests can use an in-memory loader. */
+export interface AssetBackend {
+    readonly loadTexture: (url: string) => Effect.Effect<Texture, unknown>;
+    readonly unloadTexture: (url: string, texture: Texture) => Effect.Effect<void, never>;
+    readonly loadAudio: (url: string) => Effect.Effect<void, unknown>;
+    readonly unloadAudio: (url: string) => Effect.Effect<void, never>;
+}
+/** Constructor options for {@link PixiAssets}. */
+export interface PixiAssetsOptions {
+    readonly assetsBase?: string;
+    readonly backend: AssetBackend;
+    readonly concurrency?: number;
+    readonly graceSeconds?: number;
+}
+/**
+ * Pixi-backed, scoped and ref-counted AssetLoader. A scope that calls ensure owns
+ * one reference to every requested file; the references are released by its finalizer.
+ */
+export declare class PixiAssets implements AssetLoader {
+    readonly progress: Stream.Stream<number>;
+    private readonly backend;
+    private readonly base;
+    private readonly maxConcurrency;
+    private readonly graceSeconds;
+    private readonly progressRef;
+    private readonly records;
+    private readonly unloadFibers;
+    constructor(options: PixiAssetsOptions);
+    /** Ensure all files are loaded and retain them until the caller's scope closes. */
+    readonly ensure: (files: ReadonlyArray<string>) => Effect.Effect<void, AssetMissing, Scope.Scope>;
+    /** Return a loaded image/video texture, or undefined before ensure. */
+    readonly texture: (file: string) => Texture | undefined;
+    /** Return a loaded video texture, or undefined before ensure. */
+    readonly video: (file: string) => Texture | undefined;
+    private readonly acquire;
+    private readonly release;
+    private readonly unload;
+}
+/**
+ * Collect binding-referenced files in stable insertion order. Dynamic keys such
+ * as effect names, colours, labels and flow occasions are intentionally ignored.
+ * Voice patterns are deliberately excluded because they are generated per line.
+ */
+export declare const assetsFromBindings: (bindings: unknown) => ReadonlyArray<string>;

package/dist/assets/pixiAssetsBackend.d.ts

@@ -0,0 +1,3 @@
+import type { AssetBackend } from "./pixiAssets.js";
+/** Real Pixi/@pixi-sound asset backend used by the browser player. */
+export declare const pixiAssetsBackend: AssetBackend;

package/dist/audio/pixiAudio.d.ts

@@ -0,0 +1,77 @@
+import { Effect, SubscriptionRef } from "effect";
+import type { AudioChannel, AudioPlay, AudioPort, Volumes } from "@lute-lang/player";
+/** A typed failure raised by the sound backend while decoding or starting media. */
+export declare class AudioDecodeError extends Error {
+    readonly file: string;
+    readonly _tag = "AudioDecodeError";
+    constructor(file: string, cause: unknown);
+}
+/** The playback object required by {@link PixiAudio}; useful for deterministic unit tests. */
+export interface AudioPlayback {
+    readonly setVolume: (volume: number) => void;
+    readonly stop: () => void;
+    readonly ended: Effect.Effect<void>;
+}
+/** Backend seam for PixiAudio. The default implementation delegates to @pixi/sound. */
+export interface AudioBackend {
+    readonly load: (file: string) => Effect.Effect<void, AudioDecodeError>;
+    readonly play: (file: string, options: {
+        readonly loop: boolean;
+        readonly volume: number;
+    }) => Effect.Effect<AudioPlayback, AudioDecodeError>;
+    readonly unlock: Effect.Effect<void, AudioDecodeError>;
+}
+/** Constructor options for {@link PixiAudio}. */
+export interface PixiAudioOptions {
+    readonly backend: AudioBackend;
+    readonly logger?: (message: string, error?: unknown) => void;
+    readonly initialVolumes?: Volumes;
+}
+/**
+ * PixiJS/@pixi-sound implementation of the player AudioPort.
+ *
+ * Playback is deliberately best-effort: an absent optional file is logged and does
+ * not stop the story. Fade jobs run in detached Effect fibers so superseding a
+ * channel interrupts the old Clock-driven fade without interrupting the caller.
+ */
+export declare class PixiAudio implements AudioPort {
+    readonly unlocked: SubscriptionRef.SubscriptionRef<boolean>;
+    readonly unlock: Effect.Effect<void, AudioDecodeError>;
+    private readonly backend;
+    private readonly logger;
+    private readonly active;
+    private currentVolumes;
+    private readonly gate;
+    constructor(options: PixiAudioOptions);
+    /**
+     * Play a channel sound, waiting for finite sounds to end. Music without
+     * `restart` whose file is the one already playing only changes its volume,
+     * fading over `fade`, without restarting it (spec 0.41.0 §7.7).
+     */
+    readonly play: (channel: AudioChannel, soundToPlay: AudioPlay) => Effect.Effect<void>;
+    /** Fade and stop every playback currently in a channel. */
+    readonly stop: (channel: AudioChannel, fade: number) => Effect.Effect<void>;
+    /** Set master/channel gains and apply them immediately to every active instance. */
+    readonly setVolumes: (volumes: Volumes) => Effect.Effect<void>;
+    private effectiveVolume;
+    private removeRecord;
+    private readonly interruptFade;
+    private applyVolume;
+    /** Fade `record`'s live factor to `to` over `duration` seconds, starting from wherever it is now. */
+    private readonly startFade;
+    /**
+     * Step `record` through `advance(progress)` over `duration` seconds on a
+     * detached fiber, applying its volume after each step.
+     */
+    private readonly ramp;
+    /**
+     * Move a playing record to a new input volume, fading over `fade` seconds
+     * from its current level (finishing an interrupted fade-in); it keeps playing.
+     */
+    private readonly changeVolume;
+    private readonly fadeOutAndStop;
+    private readonly stopVoiceImmediately;
+    private readonly replaceMusic;
+}
+/** Construct a PixiAudio from an injected backend. */
+export declare const makePixiAudio: (options: PixiAudioOptions) => PixiAudio;

package/dist/audio/pixiSoundBackend.d.ts

@@ -0,0 +1,3 @@
+import { type AudioBackend } from "./pixiAudio.js";
+/** Real @pixi/sound backend used by the browser player. */
+export declare const pixiSoundBackend: AudioBackend;

package/dist/choice/choiceMenu.d.ts

@@ -0,0 +1,56 @@
+import { Effect, Stream } from "effect";
+import { Container } from "pixi.js";
+import type { ChoiceView } from "@lute-lang/player";
+import type { Theme } from "../engine/types.js";
+/** A menu option with the runtime's visibility verdict and authored display text. */
+export interface ChoiceOption {
+    readonly id: string;
+    readonly verdict: string;
+    readonly text?: string;
+    readonly once?: boolean;
+    readonly exit?: boolean;
+}
+type ChoiceInput = ChoiceView;
+/** Whether a runtime verdict leaves an option selectable. */
+export declare const isChoiceEnabled: (verdict: string) => boolean;
+/** Immutable keyboard/pointer navigation state. */
+export interface ChoiceNavigationState {
+    readonly ids: ReadonlyArray<string>;
+    readonly enabled: ReadonlyArray<boolean>;
+    readonly focused: number;
+}
+/** Creates navigation state, selecting the first enabled option. */
+export declare const choiceNavigation: (options: ReadonlyArray<ChoiceOption>) => ChoiceNavigationState;
+/** Applies a navigation key or a one-based digit to a menu state. */
+export declare const navigateChoice: (state: ChoiceNavigationState, key: "up" | "down" | "enter" | string) => ChoiceNavigationState | string | undefined;
+/** A vertical, keyboard and pointer accessible choice menu. */
+export declare class ChoiceMenu {
+    readonly target: Container;
+    private readonly theme;
+    private readonly panel;
+    private readonly prompt;
+    private readonly optionsLayer;
+    private readonly countdown;
+    private readonly rendered;
+    private navigation;
+    private deferred;
+    private resolveChoice;
+    private maxRemaining;
+    private remainingValue;
+    private pulsePhase;
+    constructor(parent: Container, theme: Theme);
+    /** Shows a menu and resolves with the selected option id. */
+    show: (choice: ChoiceInput, remaining: Stream.Stream<number>) => Effect.Effect<string>;
+    /** Hides the menu and removes all option children. */
+    readonly hide: Effect.Effect<void>;
+    /** Updates the countdown from a test or host without consuming a stream. */
+    readonly setRemaining: (seconds: number) => void;
+    /** Advances the countdown pulse by seconds; called by a ticker if desired. */
+    readonly tick: (dt: number) => void;
+    private readonly keydown;
+    private pointerAt;
+    private renderOptions;
+    private updateFocus;
+    private drawCountdown;
+}
+export {};

package/dist/effects/catalogue.d.ts

@@ -0,0 +1,55 @@
+import { Effect, Schema } from "effect";
+import { Container } from "pixi.js";
+import type { Behaviour } from "../engine/types.js";
+/**
+ * Names in the player effect catalogue. `custom` (a project vfx, spec 0.41.0
+ * §7.7) is not one: the presenter handles it before reaching the catalogue.
+ */
+export type EffectName = "fade" | "dissolve" | "wipeLeft" | "wipeRight" | "wipeUp" | "wipeDown" | "slideLeft" | "slideRight" | "cut" | "fadeIn" | "fadeOut" | "slideIn" | "slideOut" | "hop" | "shake" | "none" | "zoom" | "pan" | "flash" | "blur" | "tint";
+/** Values accepted in a binding effect parameter object. */
+export type EffectParams = Readonly<Record<string, number | string | boolean>>;
+/** Optional scene context needed by camera and full-screen effects. */
+export interface EffectContext {
+    readonly design?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly overlay?: Container;
+    readonly camera?: Container;
+}
+declare const EffectDecodeError_base: Schema.Class<EffectDecodeError, Schema.TaggedStruct<"EffectDecodeError", {
+    readonly effect: Schema.String;
+    readonly parameter: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Typed decoding failure for an effect name, parameter name, or parameter value. */
+export declare class EffectDecodeError extends EffectDecodeError_base {
+}
+declare const UnknownEffect_base: Schema.Class<UnknownEffect, Schema.TaggedStruct<"UnknownEffect", {
+    readonly name: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Compatibility error for callers that distinguish unknown names. */
+export declare class UnknownEffect extends UnknownEffect_base {
+}
+declare const UnknownEffectParameter_base: Schema.Class<UnknownEffectParameter, Schema.TaggedStruct<"UnknownEffectParameter", {
+    readonly effect: Schema.String;
+    readonly parameter: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Compatibility error for callers that distinguish unknown parameters. */
+export declare class UnknownEffectParameter extends UnknownEffectParameter_base {
+}
+declare const InvalidEffectParameter_base: Schema.Class<InvalidEffectParameter, Schema.TaggedStruct<"InvalidEffectParameter", {
+    readonly effect: Schema.String;
+    readonly parameter: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** Compatibility error for callers that distinguish malformed parameter values. */
+export declare class InvalidEffectParameter extends InvalidEffectParameter_base {
+}
+/** Build behaviours for one catalogue effect, returning typed decoding failures. */
+export declare const build: (name: string, target: Container, params?: EffectParams, duration?: number, ctx?: EffectContext) => Effect.Effect<ReadonlyArray<Behaviour>, EffectDecodeError>;
+/** Catalogue facade for callers that prefer an object. */
+export declare const EffectCatalogue: {
+    build: typeof build;
+};
+export {};

package/dist/engine/app.d.ts

@@ -0,0 +1,14 @@
+import { Context, Layer } from "effect";
+import type { PixiAppShape } from "./types.js";
+/** Design resolution used to lay out the stage. */
+export interface DesignSize {
+    readonly width: number;
+    readonly height: number;
+}
+declare const PixiApp_base: Context.ServiceClass<PixiApp, "Lute.Web.PixiApp", PixiAppShape>;
+/** Scoped PixiJS application and stage graph. */
+export declare class PixiApp extends PixiApp_base {
+    /** Initialize an application and attach its canvas to `element`. */
+    static layer: (element: HTMLElement, design: DesignSize, background?: number) => Layer.Layer<PixiApp, unknown>;
+}
+export {};

package/dist/engine/behaviours.d.ts

@@ -0,0 +1,35 @@
+import { Container } from "pixi.js";
+import type { Behaviour } from "./types.js";
+import type { Easing } from "./easing.js";
+/** Properties supported by a tween. */
+export interface TweenProps {
+    readonly x?: number;
+    readonly y?: number;
+    readonly alpha?: number;
+    readonly scaleX?: number;
+    readonly scaleY?: number;
+    readonly rotation?: number;
+    readonly tint?: number;
+}
+/** Wipe direction. */
+export type WipeDirection = "left" | "right" | "up" | "down";
+/** Create a pooled property tween. */
+export declare const tween: (target: Container, props: TweenProps, to: TweenProps, duration: number, easing?: Easing) => Behaviour;
+/** Create a pooled alpha tween. */
+export declare const fade: (target: Container, to: number, duration: number) => Behaviour;
+/** Crossfade two containers over a duration. */
+export declare const crossfade: (from: Container, to: Container, duration: number) => Behaviour;
+/** Shake a container around its original position. */
+export declare const shake: (target: Container, strength: number, duration: number, frequency?: number) => Behaviour;
+/** Lift a container in a single hop and return it to its baseline. */
+export declare const hop: (target: Container, height: number, duration: number) => Behaviour;
+/** Slide a container from one x coordinate to another. */
+export declare const slide: (target: Container, fromX: number, toX: number, duration: number) => Behaviour;
+/** Reveal or conceal a target with a reusable Graphics mask. */
+export declare const wipe: (target: Container, direction: WipeDirection, duration: number, reveal?: boolean) => Behaviour;
+/** Flash an overlay container and then hide it. */
+export declare const flash: (overlay: Container, colour: number, duration: number) => Behaviour;
+/** Pulse a target forever until cancelled. */
+export declare const pulse: (target: Container, scale: number, period: number) => Behaviour;
+/** Create a pooled timer behaviour. */
+export declare const delay: (seconds: number) => Behaviour;

package/dist/engine/easing.d.ts

@@ -0,0 +1,24 @@
+/** Easing functions used by the pooled scene behaviours. */
+export type Easing = (progress: number) => number;
+/** Linear interpolation progress. */
+export declare const linear: Easing;
+/** Quadratic ease in. */
+export declare const quadIn: Easing;
+/** Quadratic ease out. */
+export declare const quadOut: Easing;
+/** Quadratic ease in and out. */
+export declare const quadInOut: Easing;
+/** Cubic ease in. */
+export declare const cubicIn: Easing;
+/** Cubic ease out. */
+export declare const cubicOut: Easing;
+/** Cubic ease in and out. */
+export declare const cubicInOut: Easing;
+/** Sine ease in and out. */
+export declare const sineInOut: Easing;
+/** Back ease out. */
+export declare const backOut: Easing;
+/** Elastic ease out. */
+export declare const elasticOut: Easing;
+/** Named easing lookup used by bindings and tests. */
+export declare const easings: Readonly<Record<string, Easing>>;

package/dist/engine/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared engine contracts of the web player (docs/player/web-architecture.md):
+ * the Pixi application service, the scene layers, and the entity–behaviour
+ * model every module builds on.
+ */
+import type { Context, Deferred, Effect, Stream } from "effect";
+import type { Application, Container } from "pixi.js";
+/** Fixed scene layers, back to front. `camera` holds the actors and is what framing/moves transform. */
+export interface Layers {
+    readonly background: Container;
+    readonly cg: Container;
+    readonly camera: Container;
+    readonly actors: Container;
+    readonly video: Container;
+    readonly dialogue: Container;
+    readonly choice: Container;
+    readonly overlay: Container;
+    readonly transition: Container;
+}
+/** The Pixi application as a scoped service (initialized with WebGL, destroyed on scope close). */
+export interface PixiAppShape {
+    readonly app: Application;
+    readonly layers: Layers;
+    /** Design resolution from `bindings.canvas`; the stage is letterboxed into the element. */
+    readonly design: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** Seconds elapsed per tick. */
+    readonly frames: Stream.Stream<number>;
+}
+export type PixiAppTag = Context.Service<PixiAppShape, PixiAppShape>;
+/**
+ * A unit of per-frame behaviour attached to an entity (tween, fade, shake,
+ * typewriter, …). `update` advances by `dt` seconds and reports whether it
+ * is finished; `finish` jumps to the end state. `done` is completed by the
+ * world when the behaviour ends either way.
+ */
+export interface Behaviour {
+    readonly update: (dt: number) => "running" | "done";
+    readonly finish: () => void;
+    /** Release resources (masks, filters) after the behaviour ended. */
+    readonly dispose: () => void;
+}
+/** Owns every running behaviour; stepped once per frame by the ticker. */
+export interface WorldShape {
+    /** Run `behaviour` on `target`; completes when it finished (or was finished by `finishAll`). */
+    readonly run: (target: Container, behaviour: Behaviour) => Effect.Effect<void>;
+    /** Finish every behaviour on `target` (or all) at once. */
+    readonly finishAll: (target?: Container) => Effect.Effect<void>;
+    /** Cancel behaviours on `target` without finishing them (e.g. superseded tweens). */
+    readonly cancel: (target: Container) => Effect.Effect<void>;
+    /** Number of running behaviours (tests, debug overlay). */
+    readonly size: Effect.Effect<number>;
+}
+/** A running behaviour's completion signal, as stored by the world. */
+export interface Running {
+    readonly target: Container;
+    readonly behaviour: Behaviour;
+    readonly done: Deferred.Deferred<void>;
+}
+/** UI theme derived from `bindings.ui` (colours as 0xRRGGBB numbers). */
+export interface Theme {
+    readonly font: string;
+    readonly text: number;
+    readonly accent: number;
+    readonly panel: number;
+    readonly panelAlpha: number;
+    readonly readText: number;
+}

package/dist/engine/world.d.ts

@@ -0,0 +1,10 @@
+import { Context, Layer } from "effect";
+import type { WorldShape } from "./types.js";
+import { PixiApp } from "./app.js";
+declare const World_base: Context.ServiceClass<World, "Lute.Web.World", WorldShape>;
+/** The scene behaviour scheduler. */
+export declare class World extends World_base {
+    /** Build a world and run it from the Pixi application ticker. */
+    static readonly layer: Layer.Layer<World, never, PixiApp>;
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** Browser visual-novel player built on PixiJS and Effect. */
+export * from "./mount.js";
+export { themeFromBindings, parseColour, defaultTheme } from "./theme.js";
+export { Input } from "./input/index.js";