p2p-lockstep-kit-ui 0.1.0

package/README.md

@@ -0,0 +1,170 @@
+# p2p-lockstep-kit-ui
+
+Web Components UI shell for `p2p-lockstep-kit-network` and `p2p-lockstep-kit-session`.
+
+The UI package owns the generic app surface:
+
+- lobby page
+- signaling registration
+- peer connection
+- share link and QR code
+- game page shell
+- ready / start / undo / restart controls
+- request dialogs and toast messages
+- board host container
+
+Game projects mount their actual board into the board host and talk to the session through the runtime exposed by the UI element.
+
+## Install
+
+```bash
+npm install p2p-lockstep-kit-ui
+```
+
+The UI package depends on:
+
+```text
+p2p-lockstep-kit-network
+p2p-lockstep-kit-session
+```
+
+Game projects do not need to instantiate those packages directly for the common lobby/game flow.
+
+## Basic Usage
+
+```ts
+import "p2p-lockstep-kit-ui";
+import "p2p-lockstep-kit-ui/style.css";
+```
+
+```html
+<p2p-lockstep-app
+  game-title="Gomoku"
+  session-id="gomoku"
+></p2p-lockstep-app>
+```
+
+The default signaling server is `wss://signal.jiahengli.xyz`. Override it only when you
+run your own signaling endpoint:
+
+```html
+<p2p-lockstep-app
+  game-title="Gomoku"
+  session-id="gomoku"
+  signal-url="wss://signal.example.com"
+></p2p-lockstep-app>
+```
+
+## Mounting A Game Board
+
+```ts
+import "p2p-lockstep-kit-ui";
+import "p2p-lockstep-kit-ui/style.css";
+import type { GameRuntime, P2PLockstepAppElement } from "p2p-lockstep-kit-ui";
+
+const app = document.querySelector("p2p-lockstep-app") as P2PLockstepAppElement | null;
+
+if (!app) {
+  throw new Error("Missing p2p-lockstep-app");
+}
+
+await customElements.whenDefined("p2p-lockstep-app");
+
+const runtime = app.getRuntime() as GameRuntime | null;
+const boardHost = app.getBoardHost();
+
+if (!runtime || !boardHost) {
+  throw new Error("Lockstep UI is not ready");
+}
+
+const board = document.createElement("div");
+board.className = "h-full";
+boardHost.append(board);
+
+runtime.observer.subscribe({
+  onStateChange(snapshot) {
+    // Render board state from snapshot.history, snapshot.turn, and local/remote states.
+  },
+});
+
+board.addEventListener("click", () => {
+  runtime.actions.move({
+    // Game-specific move payload.
+  });
+});
+```
+
+## Runtime Boundary
+
+The UI exposes the runtime from the app element:
+
+```ts
+const runtime = app.getRuntime();
+```
+
+Game runtime actions:
+
+```ts
+runtime.actions.move(move);
+```
+
+Ready, start, undo, restart, approve, and reject are owned by the UI shell
+controls. Game packages should not drive those controls directly.
+
+Runtime state:
+
+```ts
+runtime.observer.subscribe({
+  onStateChange(snapshot) {},
+  onConnectionChange(connected) {},
+  onGameEvent(event) {},
+  onError(error) {},
+});
+```
+
+Network details are intentionally kept private to the UI shell for the standard flow.
+
+## Package Design
+
+```text
+game project
+  -> imports p2p-lockstep-kit-ui
+  -> mounts board into p2p-lockstep-app.getBoardHost()
+  -> sends moves through p2p-lockstep-app.getRuntime().actions
+
+p2p-lockstep-kit-ui
+  -> owns lobby/game pages and common controls
+  -> creates NetworkClient
+  -> creates session
+  -> maps session snapshots into UI state
+
+p2p-lockstep-kit-network / p2p-lockstep-kit-session
+  -> provide transport and lockstep state
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm dev
+pnpm typecheck
+pnpm build
+```
+
+The local Vite config aliases `p2p-lockstep-kit-ui`, `p2p-lockstep-kit-network`, and `p2p-lockstep-kit-session` to local source folders for development. Published consumers resolve the package dependencies normally.
+
+## Cloudflare Pages Demo
+
+`pnpm build` builds the npm library package and does not emit an `index.html`.
+Use the Pages build when deploying the demo site:
+
+```bash
+pnpm build:pages
+```
+
+Cloudflare Pages settings:
+
+```text
+Build command: pnpm build:pages
+Build output directory: dist-pages
+```

package/dist/_headers

@@ -0,0 +1,8 @@
+/
+  Cache-Control: no-store
+
+/*.html
+  Cache-Control: no-store
+
+/assets/*
+  Cache-Control: public, max-age=31536000, immutable

package/dist/app-shell.d.ts

@@ -0,0 +1,11 @@
+import type { GameRuntime } from "./types";
+export declare class P2PLockstepAppElement extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    getRuntime(): GameRuntime | null;
+    getBoardHost(): HTMLDivElement | null;
+    render(): void;
+}

package/dist/components/action-bar.d.ts

@@ -0,0 +1,9 @@
+import type { ActionBarState } from "../types";
+export declare class P2PLockstepActionBarElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    set state(value: ActionBarState);
+    get state(): ActionBarState;
+    render(): void;
+}

package/dist/components/confirm-dialog.d.ts

@@ -0,0 +1,9 @@
+import type { DialogState } from "../types";
+export declare class P2PLockstepConfirmDialogElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    set state(value: DialogState);
+    get state(): DialogState;
+    render(): void;
+}

package/dist/components/share-panel.d.ts

@@ -0,0 +1,9 @@
+import type { SharePanelState } from "../types";
+export declare class P2PLockstepSharePanelElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    set state(value: SharePanelState);
+    get state(): SharePanelState;
+    render(): Promise<void>;
+}

package/dist/components/status-panel.d.ts

@@ -0,0 +1,8 @@
+import type { StatusPanelState } from "../types";
+export declare class P2PLockstepStatusPanelElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    set state(value: StatusPanelState);
+    get state(): StatusPanelState;
+    render(): void;
+}

package/dist/components/toast-message.d.ts

@@ -0,0 +1,8 @@
+import type { ToastState } from "../types";
+export declare class P2PLockstepToastMessageElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    set state(value: ToastState);
+    get state(): ToastState;
+    render(): void;
+}

package/dist/config.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_SIGNAL_URL = "wss://signal.jiahengli.xyz";

package/dist/game/board-host.d.ts

@@ -0,0 +1,7 @@
+export declare class P2PLockstepBoardHostElement extends HTMLElement {
+    #private;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    getMount(): HTMLDivElement | null;
+    render(): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { DEFAULT_SIGNAL_URL } from "./config";
+export declare const defineP2PLockstepUi: () => void;
+export * from "./types";
+export { P2PLockstepActionBarElement } from "./components/action-bar";
+export { P2PLockstepConfirmDialogElement } from "./components/confirm-dialog";
+export { P2PLockstepSharePanelElement } from "./components/share-panel";
+export { P2PLockstepStatusPanelElement } from "./components/status-panel";
+export { P2PLockstepToastMessageElement } from "./components/toast-message";
+export { P2PLockstepBoardHostElement } from "./game/board-host";
+export { P2PLockstepLobbyPageElement } from "./pages/lobby-page";
+export { P2PLockstepGamePageElement } from "./pages/game-page";
+export { P2PLockstepAppElement } from "./app-shell";