@novely/core 0.54.0-next.3 → 0.55.0

package/dist/index.d.mts

@@ -0,0 +1,1319 @@
+//#region src/store.d.ts
+type Stored<T> = {
+  subscribe: (cb: (value: T) => void) => () => void;
+  update: (fn: (prev: T) => T) => void;
+  set: (val: T) => void;
+  get: () => T;
+};
+type Derived<T> = {
+  subscribe: (cb: (value: T) => void) => () => void;
+  get: () => T;
+};
+//#endregion
+//#region src/translations.d.ts
+declare const RU: {
+  NewGame: string;
+  HomeScreen: string;
+  ToTheGame: string;
+  Language: string;
+  NoSaves: string;
+  LoadSave: string;
+  Saves: string;
+  Settings: string;
+  Sumbit: string;
+  GoBack: string;
+  DoSave: string;
+  Auto: string;
+  Stop: string;
+  Exit: string;
+  Automatic: string;
+  Manual: string;
+  Remove: string;
+  LoadASaveFrom: string;
+  DeleteASaveFrom: string;
+  TextSpeed: string;
+  TextSpeedSlow: string;
+  TextSpeedMedium: string;
+  TextSpeedFast: string;
+  TextSpeedAuto: string;
+  CompleteText: string;
+  GoForward: string;
+  ExitDialogWarning: string;
+  ExitDialogExit: string;
+  ExitDialogBack: string;
+  OpenMenu: string;
+  CloseMenu: string;
+  MusicVolume: string;
+  SoundVolume: string;
+  VoiceVolume: string;
+  Close: string;
+  DialogOverview: string;
+};
+type BaseTranslationStrings = keyof typeof RU;
+declare const EN: Record<BaseTranslationStrings, string>;
+//#endregion
+//#region src/renderer.d.ts
+type CharacterHandle = {
+  emotion: (emotion: string, render: boolean) => void;
+  append: (className?: string, style?: string, restoring?: boolean) => void;
+  remove: (className?: string, style?: string, duration?: number, restoring?: boolean) => Promise<void>;
+  animate: (classes: string[]) => void;
+  emotions: Record<string, HTMLImageElement[]>;
+};
+type CustomActionHandle = {
+  /**
+   * Function to remove custom action from screen (and from your state if any completely)
+   */
+  remove: () => void;
+  /**
+   * Function that will give action root (element which you should add to the screen because custom actions rendered into that element)
+   */
+  setMountElement: (mountElement: null | HTMLDivElement) => void;
+};
+type AudioHandle = {
+  stop: () => void;
+  pause: () => void;
+  play: (loop: boolean) => void;
+};
+type Context = {
+  id: string;
+  get root(): HTMLElement;
+  set root(value: HTMLElement);
+  character: (character: string) => CharacterHandle;
+  background: (background: Record<string, string>) => void;
+  dialog: (content: string, name: string, character: string | undefined, emotion: string | undefined, resolve: () => void) => void;
+  choices: (question: string, choices: [name: string, active: Stored<boolean>, visible: Stored<boolean>, onselect: () => void, image: string][], resolve: (selected: number) => void) => void;
+  input: (question: string, onInput: (meta: ActionInputOnInputMeta<Lang, State>) => void, setup: ActionInputSetup, resolve: () => void) => void;
+  clear: (keep: Set<keyof DefaultActionProxy>, keepCharacters: Set<string>, keepAudio: {
+    music: Set<string>;
+    sounds: Set<string>;
+  }, resolve: () => void) => void;
+  custom: (fn: CustomHandler<Lang, State>) => CustomActionHandle;
+  /**
+   * Clears all mentioned actions except for preserved one
+   * @param preserve Action that should not be cleared
+   */
+  clearBlockingActions: (preserve: 'dialog' | 'choice' | 'input' | 'text' | undefined) => void;
+  text: (str: string, resolve: () => void) => void;
+  vibrate: (pattern: VibratePattern) => void;
+  audio: {
+    voice: (source: string, paused: Derived<boolean>) => void;
+    voiceStop: () => void;
+    music: (source: string, paused: Derived<boolean>, method: 'music' | 'sound') => AudioHandle;
+    /**
+     * Stop all sounds
+     */
+    clear: () => void;
+    /**
+     * Destroy
+     */
+    destroy: () => void;
+    /**
+     * Initialize audio service, attach events, etc
+     */
+    start: () => void;
+  };
+  loading: (shown: boolean) => void;
+  meta: {
+    get restoring(): boolean;
+    set restoring(value: boolean);
+    get preview(): boolean;
+    set preview(value: boolean);
+    get goingBack(): boolean;
+    set goingBack(value: boolean);
+  };
+};
+type Renderer = {
+  misc: {
+    /**
+     * Function to preload image sync
+     * @param image Image URL
+     * @returns Image URL
+     */
+    preloadImage: <T extends string>(image: T) => T;
+    /**
+     * Function to preload image async
+     * @param image Image URL
+     * @returns Promise
+     */
+    preloadImageBlocking: (image: string) => Promise<void>;
+    /**
+     * Function to preload audio
+     * @param source <url> pointing to the audio
+     */
+    preloadAudioBlocking: (source: string) => Promise<void>;
+  };
+  ui: {
+    /**
+     * Shows the screen
+     */
+    showScreen(name: NovelyScreen): void;
+    /**
+     * Returns current screen
+     */
+    getScreen(): NovelyScreen | (string & Record<never, never>);
+    /**
+     * Shows loading
+     *
+     * Unline `showScreen('loading')` does not change screen
+     */
+    showLoading(): void;
+    /**
+     * Hides loading
+     */
+    hideLoading(): void;
+    /**
+     * Shows prompt to exit
+     */
+    showExitPrompt(): void;
+    /**
+     * Render the game
+     */
+    start(): {
+      /**
+       * Unmount
+       */
+      unmount(): void;
+    };
+  };
+  actions: Record<string, (...args: any[]) => ValidAction>;
+  getContext: (context: string) => Context;
+  removeContext: (context: string) => void;
+};
+type RendererInitPreviewReturn = {
+  /**
+   * Assets that was used in game preview
+   */
+  assets: string[];
+};
+type RendererInit<$Language extends Lang, $Characters extends Record<string, Character<$Language>>> = {
+  characters: CharactersData<$Characters>;
+  characterAssetSizes: CharacterAssetSizes<$Characters>;
+  set: (save: Save<State>) => Promise<void>;
+  restore: (save?: Save<State>) => Promise<void>;
+  save: (type: Save<State>[2][1]) => void;
+  newGame: () => void;
+  exit: (force?: boolean) => void;
+  back: () => Promise<void>;
+  languages: $Language[];
+  /**
+   * Translation function
+   */
+  t: (key: BaseTranslationStrings, lang: Lang) => string;
+  /**
+   * Store that tracks data updates
+   */
+  storageData: Stored<StorageData<Lang, Data>>;
+  /**
+   * Store that used to communicate between renderer and core
+   */
+  coreData: Stored<CoreData>;
+  /**
+   * There is different context, and the main one which is used for game
+   */
+  mainContextKey: string;
+  preview: (save: Save<State>, name: string) => Promise<RendererInitPreviewReturn>;
+  removeContext: (name: string) => void;
+  getStateFunction: (context: string) => StateFunction<State>;
+  clearCustomActionsAtContext: (ctx: Context) => void;
+  getLanguageDisplayName: (lang: Lang) => string;
+  getCharacterColor: (character: string) => string;
+  getCharacterAssets: (character: string, emotion: string) => string[];
+  getDialogOverview: () => Promise<DialogOverview>;
+  getResourseType: (url: string) => Promise<'image' | 'audio' | 'other'>;
+  setLanguage: (language: string) => void;
+};
+//#endregion
+//#region src/storage.d.ts
+type StorageAdapter = {
+  get: () => Promise<StorageData>;
+  set: (data: StorageData) => Promise<void>;
+};
+type StorageAdapterLocalOptions = {
+  key: string;
+};
+/**
+ * Stores data in localStorage
+ */
+declare const storageAdapterLocal: ({
+  key
+}: StorageAdapterLocalOptions) => StorageAdapter;
+//#endregion
+//#region src/translation.d.ts
+type PluralType = Intl.LDMLPluralRule;
+type Pluralization = Partial<Record<PluralType, string>>;
+type AllowedContent = string | ((state: State | Data) => string | string[]) | string[] | (string | ((state: State | Data) => string | string[]))[];
+type TranslationActions = Partial<Record<string, (str: string) => string>>;
+/**
+ * Turns any allowed content into string
+ * @param c Content
+ */
+//#endregion
+//#region src/utilities/internationalization.d.ts
+declare const getLanguage$1: (languages: string[]) => string;
+//#endregion
+//#region src/types.d.ts
+type NovelyAsset = {
+  readonly source: string;
+  readonly id: string;
+  readonly type: 'audio' | 'image';
+};
+type Thenable<T> = T | Promise<T>;
+type PathItem = [null, number] | ['jump', string] | ['choice', number] | ['choice:exit'] | ['condition', string] | ['condition:exit'] | ['exit'] | ['block', string] | ['block:exit'];
+type Path = PathItem[];
+type State = Record<string, any>;
+type Data = Record<string, any>;
+type SaveDate = number;
+type SaveType = 'manual' | 'auto';
+type SaveMeta = [date: SaveDate, type: SaveType];
+type Save<S extends State = State> = [path: Path, state: S, meta: SaveMeta, state_snapshots: S[]];
+type Lang = string;
+type TypewriterSpeed = 'Slow' | 'Medium' | 'Fast' | 'Auto';
+type SoundVolume = number;
+type StorageMeta<L extends Lang = string> = [lang: L, typewriter_speed: TypewriterSpeed, music_volume: SoundVolume, sound_volume: SoundVolume, voice_volume: SoundVolume];
+type Migration = (save: unknown) => unknown;
+type StorageData<L extends Lang = string, D extends Data = Data> = {
+  saves: Save[];
+  data: D;
+  meta: StorageMeta<L>;
+};
+type Stack = {
+  value: Save;
+  back(): void;
+  push(value: Save): void;
+  clear(): void;
+};
+type NovelyScreen = 'mainmenu' | 'game' | 'saves' | 'settings';
+/**
+ * @see https://pendletonjones.com/deep-partial
+ */
+type DeepPartial<T> = unknown extends T ? T : T extends object ? { [P in keyof T]?: T[P] extends Array<infer U> ? Array<DeepPartial<U>> : T[P] extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : DeepPartial<T[P]> } : T;
+/**
+ *
+ */
+type Assign<A extends object, B extends object> = Pick<A, Exclude<keyof A, keyof B>> & B;
+type NonEmptyRecord<T extends Record<PropertyKey, unknown>> = keyof T extends never ? never : T;
+type CoreData = {
+  dataLoaded: boolean;
+  paused: boolean;
+  focused: boolean;
+};
+type StackHolder = Save[] & {
+  previous: Save | undefined;
+};
+type TranslationDescription = {
+  internal: Record<BaseTranslationStrings, string>;
+  /**
+   * IETF BCP 47 language tag
+   */
+  tag?: string;
+  /**
+   * Custom name
+   */
+  nameOverride?: string;
+  plural?: Record<string, Pluralization>;
+  actions?: TranslationActions;
+};
+type DefaultEmotions<$Characters extends Record<string, Character<Lang>>> = { [Character in keyof $Characters]?: keyof $Characters[Character]['emotions'] & string };
+type CharacterAssetSizes<$Characters extends Record<string, Character<Lang>>> = { [Character in keyof $Characters]?: {
+  width: number;
+  height: number;
+} };
+type CharactersData<$Characters extends Record<string, Character<Lang>>> = { [Character in keyof $Characters]: {
+  name: $Characters[Character]['name'];
+  emotions: Array<keyof $Characters[Character]['emotions']>;
+} };
+type AssetsPreloading = 'lazy' | 'automatic';
+type CloneFN = <T>(value: T) => T;
+type StoryOptionsStatic = {
+  /**
+   * Static mode means that story is static
+   */
+  mode: 'static';
+};
+type StoryOptionsDynamic = {
+  /**
+   * Dynamic mode means that story parts can be loaded dynamically
+   */
+  mode: 'dynamic';
+  /**
+   * Number of saves to preload story for
+   * @default 4
+   */
+  preloadSaves?: number;
+  /**
+   * Function to dynamically load story parts.
+   *
+   * When engine find's unknown scene it will run this function.
+   * @example
+   * ```
+   * const load = async (scene: string): Promise<Story> => {
+   *   if (['part_2__act_1', 'part_2__act_2', 'part_2__act_3'].includes(scene)) {
+   *     const { getStory } = await import('./part-2.ts');
+   *
+   *     return getStory(engine.action);
+   *   }
+   *
+   *   if (scene === 'end') {
+   *     return {
+   *       'end': [
+   *         engine.action.text('The End')
+   *       ]
+   *     }
+   *   }
+   *
+   *   throw new Error(`Unknown scene: ${scene}`);
+   * }
+   * ```
+   */
+  load: (scene: string) => Promise<Story>;
+};
+type StoryOptions = StoryOptionsStatic | StoryOptionsDynamic;
+type OnLanguageChange<$Lang extends Lang> = (language: $Lang) => void;
+interface NovelyInit<$Language extends Lang, $Characters extends Record<string, Character<NoInfer<$Language>>>, $State extends State, $Data extends Data, $Actions extends Record<string, (...args: any[]) => ValidAction>> {
+  /**
+   * An object containing the characters in the game.
+   * @example
+   * ```ts
+   * const engine = novely({
+   *  characters: {
+   *   // Character ID
+   *   Alexei: {
+   *    name: 'Alexei',
+   *    color: '#f60002',
+   *    emotions: {
+   *     hopeful: './hopeful.png'
+   *    }
+   *   }
+   *  }
+   * })
+   * ```
+   */
+  characters: $Characters;
+  /**
+   * Define default emotions for characters
+   * @example
+   * ```ts
+   * const engine = novely({
+   *  characters: {
+   *   Yuki: {
+   *    name: 'Yuki',
+   *    color: '#f595f6',
+   *    emotions: {
+   *     normal: './normal.png'
+   *    }
+   *   }
+   *  },
+   *  defaultEmotions: {
+   *   Yuki: 'normal'
+   *  }
+   * });
+   *
+   * engine.script({
+   *  start: [
+   *    // Without emotion!
+   *    engine.action.showCharacter('Yuki')
+   *  ]
+   * })
+   * ```
+   */
+  defaultEmotions?: DefaultEmotions<NoInfer<$Characters>>;
+  /**
+   * Character asset sizes. We need width-height pair to render character, but we get it only after the assets are loaded. However, using that option we can use width-height before load.
+   * @example
+   * ```
+   * import peter_the_great from './assets/peter_the_great.png?width=800&height=1200';
+   *
+   * const engine = novely({
+   *   characters: {
+   *     Peter: {
+   *       name: 'Peter',
+   *       color: '#c04931',
+   *       emotions: {
+   *         normal: peter_the_great
+   *       }
+   *     }
+   *   },
+   *   characterAssetSizes: {
+   *     Peter: {
+   *       width: 800,
+   *       height: 1200
+   *     }
+   *   }
+   * })
+   * ```
+   */
+  characterAssetSizes?: CharacterAssetSizes<NoInfer<$Characters>>;
+  /**
+   * An object that provides access to the game's storage system.
+   * @default storageAdapterLocal({ key: 'novely-game-storage' })
+   */
+  storage?: StorageAdapter;
+  /**
+   * Delay loading data until Promise is resolved
+   */
+  storageDelay?: Promise<void>;
+  /**
+   * A function that returns a Renderer object used to display the game's content
+   */
+  renderer: (initializationData: RendererInit<NoInfer<$Language>, NoInfer<$Characters>>) => Renderer & {
+    actions: $Actions;
+  };
+  /**
+   * An optional property that specifies the initial screen to display when the game starts
+   */
+  initialScreen?: NovelyScreen;
+  /**
+   * An object containing the translation functions used in the game
+   * @see https://novely.pages.dev/guide/translation.html Docs
+   * @example
+   * ```ts
+   * import { novely, EN } from 'novely';
+   *
+   * const engine = novely({
+   *  translation: {
+   *   internal: EN,
+   *   // Optional IETF BCP 47 language tag
+   *   tag: 'en-US',
+   *   plural: {
+   *
+   *   },
+   *   actions: {
+   *
+   *   }
+   *  }
+   * })
+   * ```
+   */
+  translation: Record<$Language, TranslationDescription>;
+  /**
+   * Initial state value
+   *
+   * State is a local value bound to one save
+   */
+  state?: $State;
+  /**
+   * Initial data value
+   *
+   * Data is a global value shared between saves
+   */
+  data?: $Data;
+  /**
+   * Enable autosaves or disable
+   * @default true
+   */
+  autosaves?: boolean;
+  /**
+   * Migration from old saves to newer
+   */
+  migrations?: Migration[];
+  /**
+   * For saves Novely uses `throttle` function. This might be needed if you want to control frequency of saves to the storage
+   * @default 850
+   */
+  throttleTimeout?: number;
+  /**
+   * Limits how many assets can be downloaded parallelly
+   * @default 15
+   */
+  parallelAssetsDownloadLimit?: number;
+  /**
+   * Custom language detector
+   * @param languages Supported languages
+   * @param original Original function that novely, could be used as fallback
+   * @example
+   * ```ts
+   * const engine = novely({
+   * 	getLanguage(languages, original) {
+   * 		if (!sdk) return original(languages);
+   *
+   * 		return sdk.environment.i18n.lang // i.e. custom language from some sdk
+   * 	}
+   * })
+   * ```
+   */
+  getLanguage?: (languages: NoInfer<$Language>[], original: typeof getLanguage$1) => $Language | (string & Record<never, never>);
+  /**
+   * Ignores saved language, and uses `getLanguage` to get it on every engine start
+   * @default false
+   */
+  overrideLanguage?: boolean;
+  /**
+   * Show a prompt before exiting a game
+   * @default true
+   */
+  askBeforeExit?: boolean;
+  /**
+   * "automatic" will try to preload assets when possible
+   *
+   * "lazy" will load assets only when they are shown
+   *
+   * @default "automatic"
+   */
+  preloadAssets?: AssetsPreloading;
+  /**
+   * Fetching function
+   */
+  fetch?: typeof fetch;
+  /**
+   * Function for clonning operations
+   */
+  cloneFunction?: CloneFN;
+  /**
+   * When page is going to be unloaded will call `storage.set` method
+   * If 'prod' is passed enable only in production env.
+   * @default true
+   */
+  saveOnUnload?: boolean | 'prod';
+  /**
+   * The key that signifies the start of the game. It is not recommended to override this parameter.
+   *
+   * @default 'start'
+   * @example
+   * ```ts
+   * const engine = novely({
+   *   ...,
+   *   startKey: 'PART_1'
+   * })
+   *
+   * engine.script({
+   *   // now game will start from here
+   *   PART_1: [
+   *
+   *   ]
+   * })
+   * ```
+   */
+  startKey?: 'start' | (string & Record<never, never>);
+  /**
+   * Typewriter speed set by default
+   */
+  defaultTypewriterSpeed?: TypewriterSpeed;
+  /**
+   * Options to control story loading behaviour
+   */
+  storyOptions?: StoryOptions;
+  /**
+   * Will be called ONLY when language was changed by player
+   */
+  onLanguageChange?: OnLanguageChange<NoInfer<$Language>>;
+}
+type StateFunction<S extends State> = {
+  (value: DeepPartial<S> | ((prev: S) => S)): void;
+  (): S;
+};
+type EngineTypes<$Lang extends Lang = Lang, $State extends State = State, $Data extends Data = Data, $Characters extends Record<string, Character<$Lang>> = Record<string, Character<$Lang>>> = {
+  readonly l: $Lang;
+  readonly s: $State;
+  readonly d: $Data;
+  readonly c: $Characters;
+};
+type DialogOverviewEntry = {
+  /**
+   * Link to character voice
+   */
+  voice: string | undefined;
+  /**
+   * Character name
+   */
+  name: string;
+  /**
+   * Text that character says
+   */
+  text: string;
+};
+type DialogOverview = DialogOverviewEntry[];
+//#endregion
+//#region src/character.d.ts
+type Name<$Lang extends Lang> = string | Record<$Lang, string>;
+type Emotions<Emotion extends string = string> = Record<Emotion, string | NovelyAsset | (string | NovelyAsset)[]>;
+type Character<$Lang extends Lang = string> = {
+  name: Name<$Lang>;
+  color: string;
+  emotions: Emotions;
+};
+//#endregion
+//#region src/ticker.d.ts
+type TickHandler = (ticker: Ticker) => void;
+declare class Ticker {
+  listeners: Set<TickHandler>;
+  running: boolean;
+  private _factory;
+  constructor(factory: TickerFactory);
+  get deltaTime(): number;
+  get lastTime(): number;
+  add(cb: (ticker: Ticker) => void): () => void;
+  remove(cb: (ticker: Ticker) => void): void;
+  start: () => void;
+  stop: () => void;
+  detach: () => void;
+}
+declare class TickerFactory {
+  private _children;
+  private _raf;
+  private _running;
+  private _unsubscribe;
+  deltaTime: number;
+  lastTime: number;
+  constructor(paused: Derived<boolean>);
+  start(): void;
+  stop(): void;
+  fork(): Ticker;
+  check(positive: boolean): void;
+  destroy(): void;
+  detach(ticker: Ticker): void;
+  private update;
+}
+//#endregion
+//#region src/action.d.ts
+type ValidAction = ['choice', string | undefined, ...[string, unknown[], (() => boolean)?, (() => boolean)?, string?][]] | ['clear', Set<keyof DefaultActionProxy>?, Set<string>?, {
+  music: Set<string>;
+  sounds: Set<string>;
+}?] | ['condition', (state: State) => boolean, Record<string, ValidAction[]>] | ['dialog', string | undefined, TextContent<string, State>, string | undefined] | ['end'] | ['showBackground', string | NovelyAsset | BackgroundImage] | ['playMusic', string | NovelyAsset] | ['stopMusic', string | NovelyAsset] | ['pauseMusic', string | NovelyAsset] | ['playSound', audio: string | NovelyAsset, loop?: boolean] | ['pauseSound', string | NovelyAsset] | ['stopSound', string | NovelyAsset] | ['voice', string | NovelyAsset | Record<string, string | NovelyAsset>] | ['stopVoice'] | ['jump', string] | ['showCharacter', string, keyof Character['emotions'], string?, string?] | ['hideCharacter', string, string?, string?, number?] | ['animateCharacter', string, number, ...string[]] | ['wait', number | ((state: State) => number)] | ['function', FunctionAction<string, State>] | ['input', string, (meta: ActionInputOnInputMeta<string, State>) => void, ActionInputSetup?] | ['custom', CustomHandler<string, State>] | ['vibrate', ...number[]] | ['next'] | ['text', ...TextContent<string, State>[]] | ['exit'] | ['preload', string | NovelyAsset] | ['block', string] | ValidAction[];
+type Story = Record<string, ValidAction[]>;
+type TextContent<L extends string, S extends State> = string | ((state: S) => string) | Record<L, string | ((state: S) => string)>;
+type FunctionableValue<T> = T | (() => T);
+type CustomHandlerGetResultDataFunction = <T = Record<string, unknown>>(data?: T) => T;
+type CustomHandlerGetResult<I extends boolean> = {
+  /**
+   * Element for the custom action to be rendered into
+   */
+  element: I extends true ? HTMLDivElement : null;
+  /**
+   * Root node
+   */
+  root: HTMLElement;
+};
+type OnForwardFnParams = {
+  isUserRequiredAction: boolean;
+  isBlockingAction: boolean;
+  action: Exclude<ValidAction, ValidAction[]>;
+};
+type OnForwardFn = (params: OnForwardFnParams) => void;
+type CustomHandlerFunctionGetFn = <I extends boolean = true>(insert?: I) => CustomHandlerGetResult<I>;
+type CustomHandlerFunctionParameters<L extends string, S extends State> = {
+  /**
+   * Returns:
+   * - Root where entire novely is mounted
+   * - Element in which custom action could be mounted
+   *
+   * @example
+   * ```ts
+   * // pass `true` to insert element to the DOM
+   * const { root, element } = getDomNodes(true);
+   * ```
+   */
+  getDomNodes: CustomHandlerFunctionGetFn;
+  /**
+   * Function to get current Save. It can be mutated. Only use it when you know what you do
+   *
+   * @deprecated
+   */
+  getSave: () => Save<S>;
+  /**
+   * Renderer Context
+   */
+  rendererContext: Context;
+  /**
+   * Context key in which action is running
+   */
+  contextKey: string;
+  /**
+   * Function to work with custom action's state
+   *
+   * @example
+   * ```ts
+   * type Data = { name: string };
+   *
+   * const handler: CustomHandler = async ({ data }) => {
+   *   const _data = data<Data>();
+   *
+   *   if (!_data.name) {
+   *     _data.name = 'Mr. Crabs'
+   *   }
+   *
+   *   data<Data>().name // 'Mr. Crabs'
+   *
+   *   data<Data>() == _data // true
+   *
+   *   // passing object will replace object
+   *   data<Data>({ name: 'Mr. Crabs' })
+   *   data<Data>() == _data // false
+   * }
+   * ```
+   */
+  data: CustomHandlerGetResultDataFunction;
+  /**
+   * Function to access data stored at specific key.
+   * @example
+   * ```ts
+   * const handler: CustomHandler = async ({ dataAtKey }) => {
+   *   // peek at data at action with key 'action-2'
+   *   console.log(dataAtKey('action-2'))
+   * }
+   *
+   * handler.key = 'action-1'
+   * ```
+   * @deprecated
+   */
+  dataAtKey: <T extends Record<string, unknown>>(key: string) => T | null;
+  /**
+   * Function to register cleanup callbacks (executed in reverse order of registration).
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = async ({ clear, paused }) => {
+   *   const unsubscribe = paused.subscribe((paused) => {
+   *
+   *   })
+   *
+   *   clear(paused);
+   * }
+   * ```
+   */
+  clear: (fn: () => void) => void;
+  /**
+   * Overwrites `onBack` callback. Callback will be called after clearing some actions, but before starting others.
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = ({ getDomNodes, state, onBack }) => {
+   *   // some code
+   *   const update = () => button.textContent = `Clicks: ${state().clicks}`;
+   *
+   *   onBack(() => {
+   *     console.log('Backing up');
+   *     // sync state with UI
+   *     update();
+   *   })
+   * }
+   * ```
+   */
+  onBack: (fn: () => void) => void;
+  /**
+   * Overwrites `onForward` callback. Callback will be called before executing next action.
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = ({ getDomNodes, state, onForward }) => {
+   *   onForward(({ action, isBlockingAction, isUserRequiredAction }) => {
+   *     console.log(action)
+   *     console.log({ isBlockingAction, isUserRequiredAction })
+   *   })
+   * }
+   * ```
+   */
+  onForward: (fn: OnForwardFn) => void;
+  /**
+   * It will call all clear actions and remove HTML element from `getDomNodes` function
+   */
+  remove: () => void;
+  /**
+   * State function
+   */
+  state: StateFunction<S>;
+  /**
+   * Game state
+   */
+  flags: {
+    restoring: boolean;
+    goingBack: boolean;
+    preview: boolean;
+  };
+  /**
+   * Game language
+   */
+  lang: L;
+  /**
+   * Function to replace template content
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = async ({ state, templateReplace }) => {
+   *   const text = templateReplace({ en: '' }, state())
+   * }
+   * ```
+   */
+  templateReplace: (content: TextContent<L, State>, values?: State) => string;
+  /**
+   * Is game currently paused
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = async ({ clear, paused }) => {
+   *   const unsubscribe = paused.subscribe((paused) => {
+   *     // Here you can pause/resume animations, sounds, etc, etc
+   *   })
+   *
+   *   clear(paused);
+   * }
+   */
+  paused: Derived<boolean>;
+  /**
+   * Ticker
+   *
+   * @example
+   * ```ts
+   * const handler: CustomHandler = async ({ clear, ticker }) => {
+   *   const unsubscribe = ticker.add((ticker) => {
+   *     console.log(ticker.deltaTime);
+   *   })
+   *
+   *   ticker.start();
+   *
+   *   clear(unsubscribe);
+   * }
+   * ```
+   */
+  ticker: Ticker;
+  /**
+   * Fetching function.
+   * @default fetch
+   */
+  request: typeof fetch;
+};
+type CustomHandlerFunction<L extends string, S extends State> = (parameters: CustomHandlerFunctionParameters<L, S>) => Thenable<void>;
+type CustomHandlerCalling = {
+  /**
+   * Call only the last custom action of this type or not. Does not affect other custom actions
+   * @example
+   * ```ts
+   * ['custom', customSomething1]
+   * ['custom', customSomething1]
+   * ['custom', customSomething1] <-- Run only that
+   * ```
+   */
+  callOnlyLatest?: boolean;
+  /**
+   * Manually check should be skipped or not during restore
+   * @param nextActions Next actions in the restoring queue
+   */
+  skipOnRestore?: (nextActions: Exclude<ValidAction, ValidAction[]>[]) => boolean;
+};
+/**
+ * Array of URL or NovelyAsset
+ */
+type ResolvedAssets = (NovelyAsset | string)[];
+type AssetsResolverArgs = {
+  /**
+   * Fetching function
+   */
+  request: typeof fetch;
+};
+/**
+ * Function to get assets
+ */
+type AssetsResolver = (args: AssetsResolverArgs) => Thenable<ResolvedAssets>;
+type CustomHandlerInfo = CustomHandlerCalling & {
+  /**
+   * Assets used by action. When preload is "automatic", will be preloaded before action runs.
+   *
+   * In case function is provided, execution time is limited to 250ms,
+   * then returned assets or empty array (when limited)
+   * will always be used with that action
+   *
+   * @example
+   * ```ts
+   * handler.assets = [url]
+   * handler.assets = async ({ request }) => {
+   *   return [url]
+   * }
+   * ```
+   */
+  assets?: ResolvedAssets | AssetsResolver;
+  /**
+   * When true interacting with it will be saved in history
+   */
+  requireUserAction?: boolean;
+  /**
+   * Id by which we will determine what action is which
+   */
+  id: string | symbol;
+  /**
+   * Key by which we will save the custom action's data. It includes cleanup function's provided by `clear` and data in `data` function
+   *
+   * It can be a name of action or more specific thing. In example for custom `showCharacter` it may be `show-character-${character}
+   */
+  key: string;
+};
+type CustomHandler<L extends string = string, S extends State = State> = CustomHandlerFunction<L, S> & CustomHandlerInfo;
+interface ActionInputOnInputMeta<L extends string, S extends State> {
+  /**
+   * Input Element itself
+   */
+  input: HTMLInputElement;
+  /**
+   * Function to show error message or hide it
+   * @param error Error message or empty string to remove it
+   */
+  error: (error: string) => void;
+  /**
+   * Input Event
+   */
+  event: InputEvent & {
+    currentTarget: HTMLInputElement;
+  };
+  /**
+   * Sanitized `input.value`
+   */
+  value: string;
+  /**
+   * Language
+   */
+  lang: L;
+  /**
+   * State function
+   */
+  state: StateFunction<S>;
+}
+type FunctionActionProps<L extends Lang, S extends State> = {
+  restoring: boolean;
+  goingBack: boolean;
+  preview: boolean;
+  /**
+   * Language
+   */
+  lang: L;
+  /**
+   * State function
+   */
+  state: StateFunction<S>;
+};
+type ChoiceCheckFunctionProps<L extends Lang, S extends State> = {
+  /**
+   * Language
+   */
+  lang: L;
+  /**
+   * State
+   */
+  state: S;
+};
+type ChoiceOnSelectFunctionProps = {
+  /**
+   * Triggers `active` and `visible` properties computation
+   */
+  recompute: () => void;
+};
+type ChoiceCheckFunction<L extends Lang, S extends State> = (props: ChoiceCheckFunctionProps<L, S>) => boolean;
+type ChoiceOnSelectFunction = (props: ChoiceOnSelectFunctionProps) => void;
+type ConditionCheckFunction<S extends State, R extends string | true | false> = (state: S) => R;
+type FunctionAction<L extends string, S extends State> = (props: FunctionActionProps<L, S>) => Thenable<void>;
+type ActionInputSetupCleanup = () => void;
+type ActionInputSetup = (input: HTMLInputElement) => ActionInputSetupCleanup | void;
+type BackgroundImage = Record<string, string | NovelyAsset>;
+type VoiceAction<L extends Lang> = (params: string | NovelyAsset | Partial<Record<L, string | NovelyAsset>>) => ValidAction;
+type ActionChoiceChoiceObject<L extends Lang, S extends State> = {
+  title: TextContent<L, S>;
+  children: ValidAction[];
+  active?: ChoiceCheckFunction<L, S>;
+  visible?: ChoiceCheckFunction<L, S>;
+  onSelect?: ChoiceOnSelectFunction;
+  image?: string | NovelyAsset;
+};
+type ActionChoiceChoice<L extends Lang, S extends State> = [title: TextContent<L, S>, actions: ValidAction[], active?: ChoiceCheckFunction<L, S>, visible?: ChoiceCheckFunction<L, S>, onSelect?: ChoiceOnSelectFunction, image?: string | NovelyAsset];
+type ActionProxy<Characters extends Record<string, Character>, Languages extends Lang, S extends State> = {
+  choice: {
+    (...choices: ActionChoiceChoice<Languages, S>[]): ValidAction;
+    (question: TextContent<Languages, S>, ...choices: ActionChoiceChoice<Languages, S>[]): ValidAction;
+  };
+  clear: (keep?: Set<keyof DefaultActionProxy>, keepCharacters?: Set<string>, keepAudio?: {
+    music: Set<string>;
+    sounds: Set<string>;
+  }) => ValidAction;
+  condition: <T extends string | true | false>(condition: ConditionCheckFunction<S, T>, variants: Record<T extends true ? 'true' : T extends false ? 'false' : T, ValidAction[]>) => ValidAction;
+  exit: () => ValidAction;
+  dialog: {
+    <C extends keyof Characters>(character: C, content: TextContent<Languages, S>, emotion?: keyof Characters[C]['emotions']): ValidAction;
+    (character: undefined, content: TextContent<Languages, S>, emotion?: undefined): ValidAction;
+    (character: string, content: TextContent<Languages, S>, emotion?: undefined): ValidAction;
+  };
+  end: () => ValidAction;
+  showBackground: {
+    (background: string | NovelyAsset): ValidAction;
+    <T extends Record<string, string | NovelyAsset>>(background: NonEmptyRecord<T>): ValidAction;
+  };
+  playMusic: (audio: string | NovelyAsset) => ValidAction;
+  pauseMusic: (audio: string | NovelyAsset) => ValidAction;
+  stopMusic: (audio: string | NovelyAsset) => ValidAction;
+  playSound: (audio: string | NovelyAsset, loop?: boolean) => ValidAction;
+  pauseSound: (audio: string | NovelyAsset) => ValidAction;
+  stopSound: (audio: string | NovelyAsset) => ValidAction;
+  /**
+   * Plays voice
+   *
+   * @example
+   * ```
+   * engine.script({
+   *   start: [
+   *     engine.action.voice('./rick-astley-never-gonna-give-you-up.mp3'),
+   *     engine.action.say('Rick', 'Never gonna give you up'),
+   *   ]
+   * })
+   * ```
+   */
+  voice: VoiceAction<Languages>;
+  /**
+   * Stops currently playing voice
+   */
+  stopVoice: () => ValidAction;
+  jump: (scene: string) => ValidAction;
+  showCharacter: <C extends keyof Characters>(character: C, emotion?: keyof Characters[C]['emotions'], className?: string, style?: string) => ValidAction;
+  hideCharacter: (character: keyof Characters, className?: string, style?: string, duration?: number) => ValidAction;
+  animateCharacter: (character: keyof Characters, classes: string) => ValidAction;
+  wait: (time: number | ((state: State) => number)) => ValidAction;
+  function: (fn: FunctionAction<Languages, S>) => ValidAction;
+  input: (question: TextContent<Languages, S>, onInput: (meta: ActionInputOnInputMeta<Languages, S>) => void, setup?: ActionInputSetup) => ValidAction;
+  custom: (handler: CustomHandler<Languages, S> | CustomHandler) => ValidAction;
+  vibrate: (...pattern: number[]) => ValidAction;
+  next: () => ValidAction;
+  text: (...text: TextContent<Languages, S>[]) => ValidAction;
+  preload: (source: string | NovelyAsset) => ValidAction;
+  block: (scene: string) => ValidAction;
+};
+type DefaultActionProxy = ActionProxy<Record<string, Character>, Lang, State>;
+type GetActionParameters<T extends Capitalize<keyof DefaultActionProxy>> = Parameters<DefaultActionProxy[Uncapitalize<T>]>;
+type VirtualActions<$Characters extends Record<string, Character>, $Lang extends Lang, $State extends State> = {
+  choice: (question: TextContent<$Lang, $State>, ...choices: ActionChoiceChoiceObject<$Lang, $State>[]) => ValidAction;
+  say: (character: keyof $Characters, content: TextContent<$Lang, $State>) => ValidAction;
+};
+//#endregion
+//#region src/type-utils.d.ts
+type ConditionParams<T> = T extends EngineTypes<any, infer $State, any, any> ? $State : never;
+type ChoiceParams<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? ChoiceCheckFunctionProps<$Lang, $State> : never;
+type FunctionParams<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? FunctionActionProps<$Lang, $State> : never;
+type InputHandler<T> = T extends EngineTypes<infer $Lang, infer $State, any, any> ? ActionInputOnInputMeta<$Lang, $State> : never;
+/**
+ * @example
+ * ```ts
+ * type Types = TypesFromEngine<typeof engine>;
+ * ```
+ */
+type TypesFromEngine<T> = T extends {
+  types: EngineTypes<infer $Lang, infer $State, infer $Data, infer $Characters> | null;
+} ? EngineTypes<$Lang, $State, $Data, $Characters> : never;
+//#endregion
+//#region src/novely.d.ts
+declare const novely: <$Language extends string, $Characters extends Record<string, Character<$Language>>, $State extends State, $Data extends Data, $Actions extends Record<string, (...args: any[]) => ValidAction>>({
+  characters,
+  characterAssetSizes,
+  defaultEmotions,
+  storage,
+  storageDelay,
+  renderer: createRenderer,
+  initialScreen,
+  translation,
+  state: defaultState,
+  data: defaultData,
+  autosaves,
+  migrations,
+  throttleTimeout,
+  getLanguage,
+  overrideLanguage,
+  askBeforeExit,
+  preloadAssets,
+  parallelAssetsDownloadLimit,
+  fetch: request,
+  cloneFunction: clone,
+  saveOnUnload,
+  startKey,
+  defaultTypewriterSpeed,
+  storyOptions,
+  onLanguageChange
+}: NovelyInit<$Language, $Characters, $State, $Data, $Actions>) => {
+  /**
+   * Function to set game script
+   *
+   * @example
+   * ```ts
+   * engine.script({
+   *   start: [
+   *     action.function(() => {})
+   *   ]
+   * })
+   * ```
+   */
+  script: (part: Story) => Promise<void>;
+  /**
+   * Get actions
+   *
+   * @example
+   * ```ts
+   * engine.script({
+   *   start: [
+   *     action.function(() => {})
+   *   ]
+   * })
+   * ```
+   */
+  action: $Actions & ActionProxy<$Characters, $Language, $State> & VirtualActions<$Characters, $Language, $State>;
+  /**
+   * State bound to `$MAIN` game context
+   * @deprecated Use `state` function provided from action arguments
+   */
+  state: StateFunction<State>;
+  /**
+   * Store data between games
+   *
+   * @example
+   * ```ts
+   * engine.script({
+   *   start: [
+   *     action.function(() => {
+   *       // Paid content should be purchased only once
+   *       // So it will be available in any save
+   *       data({ paid_content_purchased: true })
+   *     })
+   *   ]
+   * })
+   * ```
+   */
+  data: StateFunction<$Data>;
+  /**
+   * Used in combination with type utilities
+   * @example
+   * ```ts
+   * import type { TypesFromEngine, ConditionParams, StateFunction } from '@novely/core';
+   *
+   * type Types = TypesFromEngine<typeof engine>;
+   *
+   * const conditionCheck = (state: StateFunction<ConditionParams<Types>>) => {
+   *   return state.age >= 18;
+   * }
+   * ```
+   */
+  types: EngineTypes<$Language, $State, $Data, $Characters> | null;
+  /**
+   * Replaces content inside {{braces}} using global data
+   * @example
+   * ```ts
+   * data({ name: 'Alexei' })
+   *
+   * templateReplace('{{name}} is our hero')
+   * templateReplace({
+   *  en: (data) => 'Hello, ' + data.name
+   * })
+   * ```
+   */
+  templateReplace(content: TextContent<$Language, $Data>): string;
+  /**
+   * Same as `templateReplace` but uses state and requires explicitly providing it
+   */
+  templateReplaceState(content: TextContent<$Language, $State>, state: State): string;
+  /**
+   * Cancel data loading, hide UI, ignore page change events
+   * Data updates still will work in case Novely already was loaded
+   */
+  destroy(): void;
+  /**
+   * Funtion to get current storage data
+   *
+   * @example
+   * ```ts
+   * const currentStorageData = engine.getCurrentStorageData();
+   * ```
+   */
+  getCurrentStorageData: () => StorageData<$Language, $Data> | null;
+  /**
+   * Function to set storage data. Using this function is not recommended.
+   *
+   * @deprecated
+   * @example
+   * ```ts
+   * const currentStorageData = engine.getCurrentStorageData();
+   *
+   * if (currentStorageData) {
+   *   // update music volume
+   *   currentStorageData.meta[2] = 1;
+   *
+   *   setStorageData(currentStorageData)
+   * }
+   * ```
+   */
+  setStorageData: (data: StorageData<$Language, $Data>) => void;
+  /**
+   * Function to control paused state. Custom Actions are provided with `paused` store they can subscribe to.
+   * This function will notify Custom Actions. Pause state can be used when showing ads.
+   * @example
+   * ```ts
+   * sdk.on('pause' () => engine.setPaused(true));
+   * sdk.on('resume', () => engine.setPaused(false));
+   * ```
+   */
+  setPaused: (paused: boolean) => void;
+  /**
+   * Function to control focused state. It will affect `paused` store passed to Custom Actions.
+   * This function can be used to pause game when it's not focused.
+   * @example
+   * ```ts
+   * import { pauseOnBlur } from '@novely/core';
+   *
+   * // Will subscribe to blur/focus events and call `setFocused`
+   * pauseOnBlur(engine);
+   *
+   * // OR
+   *
+   * sdk.on('focus' () => engine.setFocused(true));
+   * sdk.on('blur', () => engine.setFocused(false));
+   * ```
+   */
+  setFocused: (focused: boolean) => void;
+};
+//#endregion
+//#region src/extend-actions.d.ts
+type Part = Record<string, (...args: any[]) => ValidAction>;
+/**
+ * Extens core action with custom actions
+ * @param base Actions object you will extend, `engine.action`
+ * @param extension Actions object you will extend with
+ * @example
+ * ```ts
+ * const action = extendAction(engine.action, {
+ *   particles: (options: Parameters<typeof particles>[0]) => {
+ *     return ['custom', particles(options)]
+ *   }
+ * })
+ * ```
+ */
+declare const extendAction: <Part0 extends Part, Part1 extends Part>(base: Part0, extension: Part1) => Readonly<Assign<Part0, Part1>>;
+//#endregion
+//#region src/asset.d.ts
+/**
+ * Memoizes and returns an asset selection object based on provided file variants.
+ * The selected asset depends on the client's support for various formats.
+ *
+ * @param {...string} variants - A variable number of strings, each representing a potential asset file URL.
+ * @returns {NovelyAsset} An object representing the selected asset with `source` and `type` properties.
+ *
+ * @throws {Error} If in DEV mode and no arguments are provided.
+ * @example
+ * ```
+ * import { asset } from 'novely';
+ *
+ * // Passed first have higher priority
+ * const classroom = asset(
+ *   'classroom.avif',
+ *   'classroom.webp',
+ *   'classroom.jpeg'
+ * );
+ *
+ * setTimeout(() => {
+ *   console.log(classroom.source);
+ * }, 100);
+ * ```
+ */
+declare const asset: {
+  (...variants: string[]): NovelyAsset;
+  image(source: string): NovelyAsset;
+  audio(source: string): NovelyAsset;
+};
+//#endregion
+//#region src/browser-events.d.ts
+declare const pauseOnBlur: (engine: {
+  setFocused: (focused: boolean) => void;
+}) => {
+  unsubscribe: () => void;
+};
+//#endregion
+export { type ActionChoiceChoice, type ActionChoiceChoiceObject, type ActionInputOnInputMeta, type ActionInputSetup, type ActionInputSetupCleanup, type ActionProxy, type AllowedContent, type AudioHandle, type BackgroundImage, type BaseTranslationStrings, type Character, type CharacterAssetSizes, type CharacterHandle, type CharactersData, type ChoiceCheckFunction, type ChoiceCheckFunctionProps, type ChoiceOnSelectFunction, type ChoiceOnSelectFunctionProps, type ChoiceParams, type ConditionCheckFunction, type ConditionParams, type Context, type CoreData, type CustomActionHandle, type CustomHandler, type CustomHandlerFunction, type CustomHandlerFunctionGetFn, type CustomHandlerFunctionParameters, type CustomHandlerGetResult, type CustomHandlerGetResultDataFunction, type CustomHandlerInfo, type Data, type DeepPartial, type DefaultActionProxy, type Derived, EN, type Emotions, type EngineTypes, type FunctionParams, type FunctionableValue, type GetActionParameters, type InputHandler, type Lang, type NovelyAsset, type NovelyInit, type NovelyScreen, type Path, type PathItem, type PluralType, type Pluralization, RU, type Renderer, type RendererInit, type RendererInitPreviewReturn, type Save, type Stack, type StackHolder, type State, type StateFunction, type StorageAdapter, type StorageData, type StorageMeta, type Stored, type Story, type TextContent, type Thenable, type Ticker, type TranslationActions, type TypesFromEngine, type TypewriterSpeed, type ValidAction, asset, extendAction, novely, pauseOnBlur, storageAdapterLocal };
+//# sourceMappingURL=index.d.mts.map