@pkhex-everywhere/react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @pkhex-everywhere/react
 
+## 0.2.0
+
+### Minor Changes
+
+- fb0df12: Binary inputs take `Uint8Array`, `ArrayBuffer`, `Blob` or `File`, and binary outputs return `Uint8Array`. `game.load(data, fileName?)` takes the name from a `File`. Generated methods and hooks document whether they need a loaded save or an open draft. A missing draft fails with the new `no-draft` error code instead of `not-found`.
+- 938f28c: `createEngine()` starts downloading the runtime as soon as it's created in a browser (`{ lazy: true }` opts out) and reports `engine.status` with file download progress through `engine.onStatusChange`. `wasmHost()` returns one shared runtime per page, so several engines on a page all get changes and events.
+- eab17a2: `react` adds `useEngineStatus()` and `<RequireGame fallback>`, and `useQuery` rewrites `no-save` and `no-draft` messages to name the call and the fix. `engine` no longer exports `createClient`, `affects`, `queryTopics`, `Invoke`, `AssemblyExports` or `EngineExports`, and `engine.call` is gone.
+
+### Patch Changes
+
+- Updated dependencies [fb0df12]
+- Updated dependencies [938f28c]
+- Updated dependencies [38e32c9]
+- Updated dependencies [eab17a2]
+  - @pkhex-everywhere/engine@0.2.0
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -10,38 +10,82 @@ npm install @pkhex-everywhere/engine @pkhex-everywhere/react
 
 ## Example
 
+This app opens a save from a file input, lists the party and downloads the edited save:
+
 ```tsx
-import { Suspense } from 'react'
+import { Suspense, type ChangeEvent } from 'react'
 import { createEngine } from '@pkhex-everywhere/engine'
-import { EngineProvider, useParty } from '@pkhex-everywhere/react'
+import { EngineProvider, RequireGame, useEngineStatus, useLoadedGame, useParty } from '@pkhex-everywhere/react'
 
 const engine = createEngine()
 
+function Booting() {
+  const { loaded, total } = useEngineStatus()
+  return <progress value={loaded} max={total || 1} />
+}
+
+function OpenSave() {
+  const { load } = useLoadedGame()
+  const open = (event: ChangeEvent<HTMLInputElement>) => {
+    const file = event.target.files?.[0]
+    if (file) void load(file)
+  }
+  return <input type="file" onChange={open} />
+}
+
 function Party() {
   const { party } = useParty()
   return (
-    <ul>
+    <ul id="party">
       {party.map((pokemon) => (
-        <li key={pokemon.id}>
-          {pokemon.species} Lv. {pokemon.level}
-        </li>
+        <li key={pokemon.id}>{pokemon.species}</li>
       ))}
     </ul>
   )
 }
 
+function Download() {
+  const { export: exportSave } = useLoadedGame()
+  const download = async () => {
+    const { bytes, fileName } = await exportSave()
+    const url = URL.createObjectURL(new Blob([bytes]))
+    const link = document.createElement('a')
+    link.href = url
+    link.download = fileName
+    link.click()
+    setTimeout(() => URL.revokeObjectURL(url))
+  }
+  return <button onClick={download}>Download</button>
+}
+
 export function App() {
   return (
     <EngineProvider engine={engine}>
-      <Suspense fallback="Loading…">
-        <Party />
+      <Suspense fallback={<Booting />}>
+        <RequireGame fallback={<OpenSave />}>
+          <Party />
+          <Download />
+        </RequireGame>
       </Suspense>
     </EngineProvider>
   )
 }
 ```
 
-Load a save with `useLoadedGame().load(base64, fileName)` or `engine.game.load` before rendering hooks that read it.
+The Suspense fallback shows the runtime download with `useEngineStatus()`. `<RequireGame>` renders its fallback until a save is loaded, then its children. If the runtime fails to load, the hooks throw the error to the nearest error boundary.
+
+CI builds this app from the packed packages and runs it.
+
+## Hooks that need a save
+
+Most hooks throw `no-save` when no save is loaded, so render them inside `<RequireGame>`. Hover a hook to see what it needs. A hook that runs without a save fails with a message naming the call and the fix, and the error's `code` stays `no-save`. The same goes for `no-draft`.
+
+These work without a save:
+
+- `useEngineStatus()`
+- `useEngine()`
+- `useLoadedGame()`, where `game` is `null` until a save is loaded
+- `useQuery` with `game.get`, `game.version`, `game.blankVersions`, `catalog.names` and the `plugins.*` queries
 
 ## License
 

package/dist/RequireGame.d.ts

@@ -0,0 +1,5 @@
+import type { ReactNode } from 'react';
+export declare function RequireGame({ fallback, children }: {
+    fallback?: ReactNode;
+    children?: ReactNode;
+}): ReactNode;

package/dist/generated/hooks.d.ts

@@ -1,43 +1,66 @@
-import type { Base64, ItemHandle, PokemonHandle, PokemonPatch, TrainerGender } from '@pkhex-everywhere/engine';
+import type { Binary, ItemHandle, PokemonHandle, PokemonPatch, TrainerGender } from '@pkhex-everywhere/engine';
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function useBox(): {
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     addEncounter: (index: number) => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
-    addFromFile: (bytes: Base64) => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
+    addFromFile: (bytes: Binary) => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
     box: import("@pkhex-everywhere/engine").PokemonSummary[];
 };
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function useEvents(): {
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     giveTickets: (includeOldSeaMap: boolean) => Promise<string[]>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setFlag: (index: number, value: boolean) => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setWork: (index: number, value: number) => Promise<void>;
     events: import("@pkhex-everywhere/engine").SaveEvents | null;
 };
 export declare function useLoadedGame(): {
     close: () => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     export: () => Promise<import("@pkhex-everywhere/engine").ExportedSave>;
     file: () => Promise<import("@pkhex-everywhere/engine").LoadedSave | null>;
-    load: (data: Base64, fileName: string) => Promise<void>;
+    load: (data: Binary, fileName?: string | null) => Promise<void>;
     loadBlank: (version: number) => Promise<void>;
     game: import("@pkhex-everywhere/engine").SaveSummary | null;
 };
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function useInventory(): {
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setItem: (at: ItemHandle, count: number) => Promise<void>;
     inventory: import("@pkhex-everywhere/engine").Pouch[];
 };
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function useParty(): {
     party: import("@pkhex-everywhere/engine").PokemonSummary[];
 };
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function usePokemon(at: PokemonHandle): {
+    /** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
     addToBox: () => Promise<import("@pkhex-everywhere/engine").AddedPokemon>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     clone: () => Promise<void>;
+    /** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
     commit: () => Promise<import("@pkhex-everywhere/engine").PokemonId>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     edit: () => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setLevel: (level: number) => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     update: (patch: PokemonPatch) => Promise<void>;
     pokemon: import("@pkhex-everywhere/engine").PokemonSummary;
 };
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 export declare function useTrainer(): {
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setBattlePoints: (value: number) => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setGender: (gender: TrainerGender) => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setMoney: (amount: number) => Promise<void>;
+    /** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
     setName: (name: string) => Promise<void>;
     trainer: import("@pkhex-everywhere/engine").TrainerCard;
 };

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { EngineProvider, useEngine } from './EngineProvider';
 export { useQuery, type CallArgs, type CallResult } from './useQuery';
+export { useEngineStatus } from './useEngineStatus';
+export { RequireGame } from './RequireGame';
 export * from './generated/hooks';
 export { usePokemonDetails } from './usePokemonDetails';

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createContext, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { EngineError, affects, queryTopics } from "@pkhex-everywhere/engine";
+import { EngineError } from "@pkhex-everywhere/engine";
+import { affects, call, queryTopics } from "@pkhex-everywhere/engine/internal";
 import { jsx } from "react/jsx-runtime";
 //#region src/cache.ts
 var QueryCache = class {
@@ -91,33 +92,59 @@ function useEngine() {
 }
 //#endregion
 //#region src/useQuery.ts
-function useQuery(call, ...args) {
+var fixes = {
+	"no-save": (name) => `${name} needs a loaded save. Load one with useLoadedGame().load(file) and wrap the component in <RequireGame>.`,
+	"no-draft": (name) => `${name} needs an open draft. Open one with usePokemon(at).edit() or .clone() first.`
+};
+function explain(name, error) {
+	if (!(error instanceof EngineError)) return error;
+	const fix = fixes[error.code];
+	return fix ? new EngineError(error.code, fix(name)) : error;
+}
+function useQuery(name, ...args) {
 	const { engine, cache } = useEngineContext();
-	const key = JSON.stringify([call, args]);
-	const entry = useSyncExternalStore(cache.subscribe, () => cache.peek(key)) ?? cache.get(key, queryTopics[call], () => engine.call(call, args));
+	const key = JSON.stringify([name, args]);
+	const load = () => call(engine, name, args).catch((error) => {
+		throw explain(name, error);
+	});
+	const entry = useSyncExternalStore(cache.subscribe, () => cache.peek(key)) ?? cache.get(key, queryTopics[name], load);
 	if (entry.status === "pending") throw entry.promise;
 	if (entry.status === "error") throw entry.error;
 	return entry.value;
 }
 //#endregion
+//#region src/useEngineStatus.ts
+function useEngineStatus() {
+	const engine = useEngine();
+	const read = () => engine.status;
+	return useSyncExternalStore(engine.onStatusChange, read, read);
+}
+//#endregion
 //#region src/generated/hooks.ts
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useBox() {
 	const engine = useEngine();
 	return {
 		box: useQuery("box.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			addEncounter: (index) => engine.box.addEncounter(index),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			addFromFile: (bytes) => engine.box.addFromFile(bytes)
 		}), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useEvents() {
 	const engine = useEngine();
 	return {
 		events: useQuery("events.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			giveTickets: (includeOldSeaMap) => engine.events.giveTickets(includeOldSeaMap),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setFlag: (index, value) => engine.events.setFlag(index, value),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setWork: (index, value) => engine.events.setWork(index, value)
 		}), [engine])
 	};
@@ -128,6 +155,7 @@ function useLoadedGame() {
 		game: useQuery("game.get"),
 		...useMemo(() => ({
 			close: () => engine.game.close(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			export: () => engine.game.export(),
 			file: () => engine.game.file(),
 			load: (data, fileName) => engine.game.load(data, fileName),
@@ -135,16 +163,21 @@ function useLoadedGame() {
 		}), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useInventory() {
 	const engine = useEngine();
 	return {
 		inventory: useQuery("inventory.get"),
-		...useMemo(() => ({ setItem: (at, count) => engine.inventory.setItem(at, count) }), [engine])
+		...useMemo(() => ({ 
+		/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
+setItem: (at, count) => engine.inventory.setItem(at, count) }), [engine])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useParty() {
 	return { party: useQuery("party.get") };
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function usePokemon(at) {
 	const engine = useEngine();
 	const pokemon = useQuery("pokemon.get", at);
@@ -152,28 +185,45 @@ function usePokemon(at) {
 	return {
 		pokemon,
 		...useMemo(() => ({
+			/** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
 			addToBox: () => engine.pokemon.addToBox(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			clone: () => engine.pokemon.clone(at),
+			/** Requires a loaded save and an open draft; throws `no-save` or `no-draft` otherwise. Wrap in `<RequireGame>`. */
 			commit: () => engine.pokemon.commit(),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			edit: () => engine.pokemon.edit(at),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setLevel: (level) => engine.pokemon.setLevel(at, level),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			update: (patch) => engine.pokemon.update(at, patch)
 		}), [engine, key])
 	};
 }
+/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 function useTrainer() {
 	const engine = useEngine();
 	return {
 		trainer: useQuery("trainer.get"),
 		...useMemo(() => ({
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setBattlePoints: (value) => engine.trainer.setBattlePoints(value),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setGender: (gender) => engine.trainer.setGender(gender),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setMoney: (amount) => engine.trainer.setMoney(amount),
+			/** Requires a loaded save; throws `no-save` otherwise. Wrap in `<RequireGame>`. */
 			setName: (name) => engine.trainer.setName(name)
 		}), [engine])
 	};
 }
 //#endregion
+//#region src/RequireGame.tsx
+function RequireGame({ fallback = null, children }) {
+	const { game } = useLoadedGame();
+	return game ? children : fallback;
+}
+//#endregion
 //#region src/usePokemonDetails.ts
 function usePokemonDetails(at) {
 	const engine = useEngine();
@@ -185,4 +235,4 @@ function usePokemonDetails(at) {
 	};
 }
 //#endregion
-export { EngineProvider, useBox, useEngine, useEvents, useInventory, useLoadedGame, useParty, usePokemon, usePokemonDetails, useQuery, useTrainer };
+export { EngineProvider, RequireGame, useBox, useEngine, useEngineStatus, useEvents, useInventory, useLoadedGame, useParty, usePokemon, usePokemonDetails, useQuery, useTrainer };

package/dist/useEngineStatus.d.ts

@@ -0,0 +1,2 @@
+import type { EngineStatus } from '@pkhex-everywhere/engine';
+export declare function useEngineStatus(): EngineStatus;

package/dist/useQuery.d.ts

@@ -3,5 +3,5 @@ type Lookup<T, Path extends string> = Path extends `${infer Head}.${infer Rest}`
 type CallFunction<Name extends CallName> = Extract<Lookup<EngineClient, Name>, (...args: never[]) => Promise<unknown>>;
 export type CallArgs<Name extends CallName> = Parameters<CallFunction<Name>>;
 export type CallResult<Name extends CallName> = Awaited<ReturnType<CallFunction<Name>>>;
-export declare function useQuery<Name extends QueryName>(call: Name, ...args: CallArgs<Name>): CallResult<Name>;
+export declare function useQuery<Name extends QueryName>(name: Name, ...args: CallArgs<Name>): CallResult<Name>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pkhex-everywhere/react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "React hooks for @pkhex-everywhere/engine.",
   "license": "GPL-3.0-or-later",
   "repository": {