// @shortplay/game-sdk — the OPTIONAL child-side author SDK (D5 progressive enhancement).
//
// This ships to untrusted third-party authors and runs INSIDE the sandboxed game iframe.
// It MUST be standalone: it does NOT import from the app's `src/` graph or use path aliases
// (so it never drags the app's tsconfig into a third party's build). The wire format below
// is VENDORED from src/runtime/protocol.ts and MUST match it exactly.
//
// The SDK is DX, NOT a security boundary (docs/07). But the child still authenticates the
// parent the same way the parent authenticates the child — there is no trustworthy origin:
//   (1) source identity — accept only `event.source === window.parent`;
//   (2) per-mount nonce — read from `location.hash` (`#sp=<nonce>`); every inbound message
//       must carry the exact same nonce, else ignore;
//   (3) schema — validate every inbound message against the parent→game shape.
// Outbound, we post to the parent with the nonce and targetOrigin '*' (the parent cannot be
// targeted by origin; it re-validates via source + nonce). NEVER trust origin.
//
// STANDARDS-FIRST (D5): on `pause`/`blur` the SDK also dispatches REAL `visibilitychange` /
// `blur` so an UNMODIFIED game (one that never registered SDK callbacks) still pauses.

// ----- controller input (shared with the games-worker serve-time input shim) --------------
//
// isGameInputMessage / dispatchControllerInput live in ./controllerInputDispatch — a SIBLING
// module in this same standalone package (not the app's src/ graph), self-contained by design so
// games-worker/src/inputShim.ts can `.toString()` the SAME functions into a literal inline
// <script> injected into every served uploaded-game HTML document (card
// bug-paired-device-taps-never-reach-the-game — a hand-rolled-bridge game that never imports this
// SDK gets that shim instead; this file's own handleInbound below covers SDK games). See that
// module's header for why the two functions must stay free of outer-scope references.
import { isGameInputMessage, dispatchControllerInput } from './controllerInputDispatch';

export { isGameInputMessage };

// ----- vendored wire format (keep byte-compatible with src/runtime/protocol.ts) -----------

const SP_PROTOCOL_VERSION = 1 as const;

const LIMITS = {
  stringMax: 128,
  scoreAbsMax: 1e15,
  eventDataMax: 16_384,
} as const;

type LifecycleCommand =
  | 'init'
  | 'focus'
  | 'blur'
  | 'pause'
  | 'resume'
  | 'resize'
  | 'stop';

interface Dims {
  w: number;
  h: number;
}

interface ParentToGameMessage {
  sp: typeof SP_PROTOCOL_VERSION;
  nonce: string;
  type: 'lifecycle';
  cmd: LifecycleCommand;
  accent?: string;
  dims?: Dims;
}

function isRecord(x: unknown): x is Record<string, unknown> {
  return typeof x === 'object' && x !== null;
}

function isBoundedString(x: unknown): x is string {
  return typeof x === 'string' && x.length > 0 && x.length <= LIMITS.stringMax;
}

const LIFECYCLE_COMMANDS: ReadonlySet<LifecycleCommand> = new Set<LifecycleCommand>([
  'init',
  'focus',
  'blur',
  'pause',
  'resume',
  'resize',
  'stop',
]);

function isDims(x: unknown): x is Dims {
  return (
    isRecord(x) &&
    typeof x.w === 'number' &&
    Number.isFinite(x.w) &&
    x.w >= 0 &&
    typeof x.h === 'number' &&
    Number.isFinite(x.h) &&
    x.h >= 0
  );
}

/** Exported for the SDK's own tests; mirrors protocol.isParentToGameMessage. */
export function isParentToGameMessage(x: unknown): x is ParentToGameMessage {
  if (!isRecord(x)) return false;
  if (x.sp !== SP_PROTOCOL_VERSION) return false;
  if (!isBoundedString(x.nonce)) return false;
  if (x.type !== 'lifecycle') return false;
  if (typeof x.cmd !== 'string' || !LIFECYCLE_COMMANDS.has(x.cmd as LifecycleCommand)) return false;
  if (x.accent !== undefined && !isBoundedString(x.accent)) return false;
  if (x.dims !== undefined && !isDims(x.dims)) return false;
  return true;
}

// ----- author API ------------------------------------------------------------------------

export interface GameDefinition {
  /** Construct the game into `container` at the given accent + initial dims. */
  build(container: HTMLElement, accent: string, dims: Dims): void;
  /** Full-play focus changed (true = focused). */
  onFocus?(focused: boolean): void;
  /** Suspend simulation. */
  onPause?(): void;
  /** Resume simulation. */
  onResume?(): void;
  /** Stage box changed. Standards-first reflow already happened; this is the explicit hook. */
  onResize?(w: number, h: number): void;
  /** Teardown imminent. */
  onStop?(): void;
}

export interface ShortPlayApi {
  /** Register the game. Sends `ready` to the parent once registered. */
  game(def: GameDefinition): void;
  /** Report a score to the platform. */
  score(value: number): void;
  /** Report an arbitrary named event (optionally with a small JSON payload). */
  event(name: string, data?: unknown): void;
}

interface SdkOptions {
  /** Test seam: the window to operate in (defaults to the real global `window`). */
  win?: Window;
  /** Test seam: the element games build into (defaults to `document.body`). */
  root?: HTMLElement;
}

export function createShortPlay(options: SdkOptions = {}): ShortPlayApi {
  const win = options.win ?? (globalThis as unknown as Window);
  const parent = win.parent;

  // (2) nonce from the URL hash: `#sp=<nonce>`. Read once at construction.
  const ownNonce = readNonce(win.location?.hash ?? '');
  const marker = win.document?.querySelector?.('meta[name="sp-game-version"]');
  const runningVersion = marker?.getAttribute('content')?.trim() || undefined;

  let definition: GameDefinition | null = null;
  // The element the game was `build()`-into (options.root, or document.body) — captured on
  // `init` so a later `input` message dispatches at the same box a real local event would.
  let gameRoot: HTMLElement | null = options.root ?? null;

  function post(message: Record<string, unknown>): void {
    if (!ownNonce) return; // no nonce ⇒ not a real ShortPlay mount; stay silent
    parent.postMessage({ sp: SP_PROTOCOL_VERSION, nonce: ownNonce, ...message }, '*');
  }

  function handleInbound(event: MessageEvent): void {
    // (1) source identity — must come from our parent frame.
    if (event.source !== parent) return;
    const data: unknown = event.data;

    // Controller input rides a SIBLING `type:'input'` message (not `'lifecycle'`) — checked
    // first so it isn't dropped by the lifecycle-only schema guard below.
    if (isGameInputMessage(data)) {
      if (data.nonce !== ownNonce) return; // (2) nonce
      dispatchControllerInput(win, gameRoot ?? win.document.body, data);
      return;
    }

    // (3) schema — must be a well-formed parent→game message.
    if (!isParentToGameMessage(data)) return;
    // (2) nonce — must match the one minted for THIS mount.
    if (data.nonce !== ownNonce) return;

    const def = definition;
    switch (data.cmd) {
      case 'init': {
        const root = options.root ?? win.document.body;
        gameRoot = root;
        const dims = data.dims ?? { w: root.clientWidth, h: root.clientHeight };
        def?.build(root, data.accent ?? '#ffffff', dims);
        return;
      }
      case 'focus':
        def?.onFocus?.(true);
        // standards-first + SYMMETRIC to `blur`'s suspension path: fire a real window 'focus'
        // so a game that paused on a window 'blur' (from `pause`) un-pauses when re-focused.
        dispatchFocus(win);
        return;
      case 'blur':
        // INPUT focus only — a blurred game (in-feed, not owning full-play; e.g. a peek/neighbor
        // cell) MUST KEEP RUNNING. We deliberately do NOT dispatch a window 'blur' here: blurring
        // must never freeze the loop. Suspension is the sole job of `pause` (below), so the feed
        // stays alive and "the play is part of the scroll".
        def?.onFocus?.(false);
        return;
      case 'pause':
        def?.onPause?.();
        // standards-first: drive real visibilitychange + blur so unmodified games pause.
        setHidden(win, true);
        dispatchVisibilityChange(win);
        dispatchBlur(win);
        return;
      case 'resume':
        def?.onResume?.();
        // SYMMETRIC to pause: restore visibility AND fire window 'focus' so a game that paused on
        // the window 'blur' above un-pauses. (The missing focus dispatch was the asymmetry that
        // left games frozen/stuck after they had been suspended.)
        setHidden(win, false);
        dispatchVisibilityChange(win);
        dispatchFocus(win);
        return;
      case 'resize':
        if (data.dims) def?.onResize?.(data.dims.w, data.dims.h);
        return;
      case 'stop':
        def?.onStop?.();
        return;
    }
  }

  win.addEventListener('message', handleInbound as EventListener);

  // HELLO ("the handshake is in progress"). Posted the moment the SDK is CONSTRUCTED — i.e. during
  // the game module's evaluation, strictly before the author calls `ShortPlay.game(...)`. It tells
  // the parent that this bundle IS bridged so it will not settle its bridge-optional classification
  // on a timer while a slow device is still booting the game (a misclassified game gets torn down
  // and rebooted on the next suspend). It carries no payload and grants nothing: `ready` is still
  // the only message that starts the lifecycle. `post` is silent without a nonce, so a bundle
  // imported outside a real ShortPlay mount stays silent here too.
  post({ type: 'boot' });

  // EXIT-KEY FORWARDING (additive, protocol v1). When the game frame holds DOM focus the PARENT
  // never sees keydowns — its "Esc to exit" affordance went dead the moment the player clicked
  // into the game. The SDK forwards the in-frame Escape as a `{ type:'exit' }` message; the host
  // exits full-play for the game that owns it (and ignores it otherwise). Games never need to
  // handle Escape themselves; an older parent's validator drops the unknown type silently.
  win.addEventListener('keydown', ((e: KeyboardEvent) => {
    if (e.key === 'Escape') post({ type: 'exit' });
  }) as EventListener);

  return {
    game(def: GameDefinition): void {
      definition = def;
      post(runningVersion ? { type: 'ready', version: runningVersion } : { type: 'ready' });
    },
    score(value: number): void {
      if (typeof value !== 'number' || !Number.isFinite(value)) return;
      if (Math.abs(value) > LIMITS.scoreAbsMax) return;
      post({ type: 'score', value });
    },
    event(name: string, data?: unknown): void {
      if (!isBoundedString(name)) return;
      if (data !== undefined) {
        try {
          if (JSON.stringify(data).length > LIMITS.eventDataMax) return;
        } catch {
          return; // unserializable (e.g. circular) → drop, don't post
        }
      }
      post(data === undefined ? { type: 'event', name } : { type: 'event', name, data });
    },
  };
}

// ----- input helpers -----------------------------------------------------------------------

/**
 * Map a pointer/touch/mouse CLIENT position to the game's LOGICAL coordinate space.
 *
 * A canvas's on-screen box (`getBoundingClientRect`) is in CSS pixels and can differ from the
 * logical `w`/`h` you simulate in — the feed cell may letterbox or CSS-scale the stage, and the
 * device pixel ratio is independent again. So `e.clientX - rect.left` is NOT a logical
 * coordinate; using it raw makes taps land in the wrong place once the box ≠ logical size (this
 * was a real lane-racer bug). Always route position-sensitive input through here.
 *
 * Pass the raw `clientX`/`clientY` from the event plus the logical dims you render against.
 * Degrades safely to identity scaling if the box has zero size (e.g. display:none).
 */
export function clientToLogical(
  canvas: HTMLCanvasElement,
  clientX: number,
  clientY: number,
  w: number,
  h: number,
): { x: number; y: number } {
  const rect = canvas.getBoundingClientRect();
  const sx = rect.width > 0 ? w / rect.width : 1;
  const sy = rect.height > 0 ? h / rect.height : 1;
  return { x: (clientX - rect.left) * sx, y: (clientY - rect.top) * sy };
}

// ----- standards-first helpers ------------------------------------------------------------

function readNonce(hash: string): string {
  // hash looks like `#sp=<nonce>` (possibly with other params). Tolerant parse.
  const m = /[#&]sp=([^&]+)/.exec(hash);
  return m?.[1] ?? '';
}

function setHidden(win: Window, hidden: boolean): void {
  try {
    Object.defineProperty(win.document, 'visibilityState', {
      configurable: true,
      get: () => (hidden ? 'hidden' : 'visible'),
    });
    Object.defineProperty(win.document, 'hidden', {
      configurable: true,
      get: () => hidden,
    });
  } catch {
    // some environments forbid redefining; the dispatched event still fires.
  }
}

function dispatchVisibilityChange(win: Window): void {
  win.document.dispatchEvent(new Event('visibilitychange'));
}

function dispatchBlur(win: Window): void {
  win.dispatchEvent(new Event('blur'));
}

function dispatchFocus(win: Window): void {
  win.dispatchEvent(new Event('focus'));
}

/**
 * Default global SDK instance, bound to the real window. Authors use `ShortPlay.game(...)`.
 * Constructed lazily on first access so the SDK can be imported in non-DOM tooling without
 * side effects (and so tests can use `createShortPlay({ win })` with a fake window).
 */
let singleton: ShortPlayApi | null = null;
export const ShortPlay: ShortPlayApi = {
  game(def) {
    (singleton ??= createShortPlay()).game(def);
  },
  score(value) {
    (singleton ??= createShortPlay()).score(value);
  },
  event(name, data) {
    (singleton ??= createShortPlay()).event(name, data);
  },
};