@fabi-play/sdk 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -84,6 +84,38 @@ export interface PointerOptions {
 }
 /** The child's hand as the mouse: it moves the pointer and clicks by staying still on a spot. */
 export declare function pointer(play: On, options?: PointerOptions): () => void;
+/** The events the remote's cursor makes in the game's page, as a Magic Remote's (a mouse). */
+export type CursorEventType = "pointermove" | "mousemove" | "pointerdown" | "mousedown" | "pointerup" | "mouseup" | "click" | "pointercancel";
+/** Where the cursor's events go (connect's options.cursor): by default the page (domCursor()). */
+export interface CursorTarget {
+	/** The game's viewport in px. */
+	size(): {
+		width: number;
+		height: number;
+	};
+	/** One event at x, y (px); buttons: 1 while OK is held, else 0. */
+	dispatch(type: CursorEventType, x: number, y: number, buttons: number): void;
+}
+/**
+ * Mouse and pointer events (pointerType 'mouse', pointerId 1) on what is under the cursor, as a Magic Remote's:
+ * pointerover/mouseover and pointerout/mouseout when it moves onto another element, a click only where the press
+ * started. Browsers without PointerEvent (old TVs) get the mouse events only. The screen draws the cursor itself.
+ */
+export declare function domCursor(doc?: Document): CursorTarget;
+/**
+ * Turns the screen's cursor messages into events on a target: moves, presses (OK down) and releases (OK up, then a
+ * click). cancel(): the cursor stops (a pause, a break, a turn) while OK is held: pointercancel and mouseup, no click.
+ */
+export declare function cursorDriver(target: CursorTarget): {
+	update(c: {
+		x: number;
+		y: number;
+		down: boolean;
+	}): void;
+	cancel(): void;
+};
+/** What became of a picture the game asked to save (HostMessage picture-result, Play.savePicture). */
+export type PictureResult = "sent" | "unavailable" | "too-big" | "error";
 /**
  * One body: for each landmark x, y (0–1, y downwards) and visibility (0–1), so 33 × 3 numbers.
  * In "player space": mirrored like a mirror, whatever camera took it, so a child moving to their left moves left.
@@ -225,7 +257,18 @@ export type HostMessage =
  */
 /**
  * pointer: only with input 'remote', true when the TV's remote also points (LG's Magic Remote): it reaches the game
- * as ordinary pointer and mouse events (hover, click with OK). Absent = false.
+ * as ordinary pointer and mouse events (hover, click with OK); or, for a game whose manifest says "remoteCursor":
+ * true, when the screen moves a cursor with the arrows (cursor messages, which the SDK turns into the same pointer
+ * and mouse events). Absent = false.
+ */
+/**
+ * pictures: a phone that can save pictures is linked now (its hello said pictures), so the game may send picture
+ * messages; it changes with a capabilities message. Absent = false.
+ */
+/**
+ * orientation: the screen's orientation when the game starts (width ≥ height: 'landscape', see orientationOf);
+ * only a game whose manifest lists 'portrait' gets 'portrait'. Informational, to choose a layout: lay out from the
+ * real viewport size all the same. Absent (older hosts) = 'landscape'.
  */
 {
 	type: "init";
@@ -242,6 +285,8 @@ export type HostMessage =
 	input?: GameInput;
 	turns?: number[];
 	pointer?: boolean;
+	pictures?: boolean;
+	orientation?: Orientation;
 }
 /** The backdrop or the view changed mid-game (video switched on or off, the camera image's fit or framing changed). */
  | {
@@ -295,6 +340,36 @@ export type HostMessage =
  | {
 	type: "turn";
 	players: number[];
+}
+/**
+ * What the screen can do for the game changed mid-game: pictures, whether a phone that can save pictures is linked
+ * now (one joined, or the last one left). init carries the first value.
+ */
+ | {
+	type: "capabilities";
+	pictures: boolean;
+}
+/**
+ * The answer to a picture message, with its id (absent if the picture had none): 'sent', the phone has it (saved,
+ * or saved once the parent allows it); 'unavailable', no phone that saves pictures is linked; 'too-big', over
+ * MAX_PICTURE_BYTES; 'error', anything else (the link dropped, the phone failed, no answer in time).
+ */
+ | {
+	type: "picture-result";
+	id?: number;
+	result: PictureResult;
+}
+/**
+ * Remote mode with "remoteCursor": true: the cursor the arrows move (see KeyCursor), x and y in fractions of the
+ * game's frame (0–1), down while OK is held. Sent when it moves and when OK goes down or up; the SDK turns it into
+ * pointer and mouse events in the game's page (pointermove, pointerdown, pointerup, click, …), as a Magic Remote's.
+ * The screen draws the cursor itself, above the game.
+ */
+ | {
+	type: "cursor";
+	x: number;
+	y: number;
+	down: boolean;
 };
 /** Why a game is paused (see HostMessage pause). */
 export type PauseReason = "user" | "distance";
@@ -336,7 +411,20 @@ export type GameMessage =
  | ({
 	type: "stats";
 	renderFps: number;
-} & GameStats);
+} & GameStats)
+/**
+ * Save a picture on the family's phone (a drawing, the photo of a wall). data: a base64 data URL, data:image/jpeg
+ * or data:image/png, at most MAX_PICTURE_BYTES, whose bytes really are that type (checkPicture); title: a name for
+ * it (MAX_PICTURE_TITLE characters); id: the game's own, echoed in picture-result. Anything else is dropped: a game
+ * can send only an image this way. The screen sends it to the phone over their direct link only, never to a
+ * server, and answers picture-result.
+ */
+ | {
+	type: "picture";
+	data: string;
+	title?: string;
+	id?: number;
+};
 /** The movements a game is played with, as its manifest lists them. */
 export type Movement = "hands" | "jump" | "squat" | "clap" | "freeze" | "lanes" | "shapes";
 /**
@@ -390,6 +478,14 @@ export interface GameManifest {
 	backdrop?: GameBackdrop[];
 	/** Optional: Fabi explains the game on the TV before calibration (see GameIntro). Absent: straight to calibration. */
 	intro?: GameIntro;
+	/**
+	 * Optional: the game's cover, the card in the catalogue (TV carousel, phone, admin): a path relative to the game's
+	 * address (no scheme, no leading /, no "." or ".." segments, no backslash, up to COVER_MAX_PATH characters, see
+	 * isCoverPath), ending in lowercase .jpg, .jpeg, .png or .webp: cover.jpg. A 16:9 image (COVER_ASPECT, within
+	 * COVER_ASPECT_TOLERANCE), recommended 1280×720 and at most COVER_MAX_BYTES; JPEG is the safest for old TV
+	 * browsers. The review checks the file; absent or broken, the catalogue falls back to another image.
+	 */
+	cover?: string;
 	/** Optional: how it can be played; absent = ['body']. Must include 'body' (Fabi Play is a movement platform); add 'remote' to be offered without a phone. */
 	inputs?: GameInput[];
 	/**
@@ -406,7 +502,27 @@ export interface GameManifest {
 	 * a game drawn on exact spots of the live video).
 	 */
 	framing?: GameFraming;
+	/**
+	 * Optional, only with 'remote' in inputs: true and, in remote mode, the arrows move a free cursor instead of making
+	 * gestures (they speed up when held, see KeyCursor) and OK presses and releases it: the game gets it as pointer and
+	 * mouse events, the same as a Magic Remote's (init.pointer true), so a game written for the pointer works with
+	 * both. Back is still the platform's pause. For games picked or drawn with a pointer (a painting game). Absent or
+	 * false: arrows and OK make gestures.
+	 */
+	remoteCursor?: boolean;
+	/**
+	 * Optional: the screen orientations the game can be played in; absent = ['landscape'] (see gameOrientations).
+	 * Non-empty, without repeats, from ORIENTATIONS. A phone alone («Gioca qui / Play here») is held upright, so it
+	 * offers only games that list 'portrait'; the TV and the tablet are landscape. A game that lists both still lays
+	 * out from its real viewport size; init.orientation says which one it started in.
+	 */
+	orientations?: Orientation[];
 }
+/**
+ * A screen's orientation: 'landscape' when its width is at least its height, else 'portrait' (see orientationOf).
+ * GameManifest.orientations lists those a game supports; HostMessage init.orientation says the one it starts in.
+ */
+export type Orientation = "landscape" | "portrait";
 /** How the screen frames the camera image for a game: see GameManifest.framing. */
 export type GameFraming = "auto" | "fixed";
 /**
@@ -550,6 +666,8 @@ export type SmoothedBody = (who: PlayerFrame | number, options?: Pick<DrawAvatar
 export declare function avatarDrawer(book: AvatarBook, scene: () => {
 	view: BackdropView | null;
 }): DrawAvatar;
+/** What savePicture takes: a canvas (any size) or a data URL (data:image/jpeg or data:image/png, base64). */
+export type PictureSource = HTMLCanvasElement | string;
 /** What the 'start' event says: who plays and how, as it was at the start (late listeners get the same; see Easy for now). */
 export interface StartInfo {
 	/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
@@ -558,8 +676,10 @@ export interface StartInfo {
 	players: readonly number[];
 	/** The language to show text in. */
 	locale: Locale;
-	/** 'tv': on a TV, children standing back; 'solo': a tablet in front of one child. */
+	/** 'tv': on a TV, children standing back; 'solo': a tablet or a phone in front of the children. */
 	mode: "tv" | "solo";
+	/** 'landscape' or 'portrait' (a phone held upright): the screen's orientation at the start, see Play.orientation. */
+	orientation: Orientation;
 	/** 'video': mirror mode, paint no opaque background; 'none': paint your own. See the backdrop event. */
 	backdrop: Backdrop;
 	/** Where the camera image is (with 'video', the video; with 'none', where the avatars stand), see toScreen; null if unknown. */
@@ -570,8 +690,12 @@ export interface StartInfo {
 	turns: readonly number[];
 	/** 'body' (the default) or 'remote': played with the TV remote, keys turned into gestures (see Play.input). */
 	input: GameInput;
-	/** With input 'remote', whether the remote also points (LG's Magic Remote; see Play.pointer). */
+	/** With input 'remote', whether the remote also points (LG's Magic Remote, or the arrows as a cursor; see Play.pointer). */
 	pointer: boolean;
+	/** Whether savePicture can reach a phone at the start (see Play.canSavePicture; the capabilities event says when it changes). */
+	canSavePicture: boolean;
+	/** The screen's sound is off: play no sound, and make every cue that sound would give visible instead. */
+	muted: boolean;
 }
 /**
  * The events of FabiPlay.on, by name, with what each listener gets. Every gesture (jump, land, squat, stand, clap,
@@ -630,6 +754,10 @@ export type EasyEvents = {
 	turn: {
 		players: number[];
 	};
+	/** What the screen can do changed: pictures, whether savePicture can reach a phone now (see canSavePicture). */
+	capabilities: {
+		pictures: boolean;
+	};
 };
 /** An event name of FabiPlay.on. */
 export type EasyEvent = keyof EasyEvents;
@@ -646,7 +774,7 @@ export type EasyEvent = keyof EasyEvents;
 export interface Easy {
 	/**
 	 * Listens to an event: a gesture by its name ('jump', 'clap', 'lane-left', …), 'start', 'hands', 'shape',
-	 * 'players', 'pause', 'resume', 'break-start', 'break-end', 'backdrop', 'turn' (see EasyEvents). Returns a function that
+	 * 'players', 'pause', 'resume', 'break-start', 'break-end', 'backdrop', 'turn', 'capabilities' (see EasyEvents). Returns a function that
 	 * stops listening.
 	 *
 	 * @example
@@ -687,8 +815,26 @@ export interface Easy {
 	readonly turns: readonly number[];
 	/** How this session is played (see Play.input); 'body' before start. */
 	readonly input: GameInput;
-	/** With input 'remote', whether the remote also points (Play.pointer; pointer() is the hand adapter); false before start. */
+	/**
+	 * With input 'remote', whether the remote also points (Play.pointer: a Magic Remote, or the arrows as a cursor with
+	 * "remoteCursor": true; either way plain pointer and mouse events). pointer() is the hand adapter. False before start.
+	 */
 	readonly hasPointer: boolean;
+	/** Whether savePicture can reach a phone now (see Play.canSavePicture); false before start. */
+	readonly canSavePicture: boolean;
+	/**
+	 * Saves a picture on the family's phone: a canvas (scaled to 1920 px at most, JPEG) or a data URL (JPEG or PNG),
+	 * with an optional title. Resolves 'sent', 'unavailable', 'too-big' or 'error' (see Play.savePicture); called before
+	 * start, it waits for it. Only TV → phone over their direct link, never to a server.
+	 *
+	 * @example
+	 * if (FabiPlay.canSavePicture) FabiPlay.savePicture(canvas, { title: 'Il nostro muro' })
+	 */
+	savePicture(source: PictureSource, opts?: {
+		title?: string;
+	}): Promise<PictureResult>;
+	/** The screen's sound is off (see StartInfo.muted); false before start. */
+	readonly muted: boolean;
 	/** Where the camera image is, with any backdrop; null if the host didn't say, and before start. */
 	readonly view: BackdropView | null;
 	/** What the screen knows about the device (see Play.device); null if it said nothing, and before start. */
@@ -764,6 +910,20 @@ export type Events = {
 	turn: Extract<HostMessage, {
 		type: "turn";
 	}>;
+	/**
+	 * What the screen can do for the game changed: pictures, whether savePicture can reach a phone now (see
+	 * Play.canSavePicture). Only when it changes.
+	 */
+	capabilities: Extract<HostMessage, {
+		type: "capabilities";
+	}>;
+	/**
+	 * Remote mode with "remoteCursor": true: the cursor the arrows move (x, y in fractions of the page, down while OK
+	 * is held). Nothing to do with it: the SDK already makes the pointer and mouse events a Magic Remote would.
+	 */
+	cursor: Extract<HostMessage, {
+		type: "cursor";
+	}>;
 };
 /**
  * The game's side of Fabi Play, from connect(): who plays, their movements, and how the game tells it is ready,
@@ -808,10 +968,43 @@ export interface Play {
 	/**
 	 * Only with input 'remote': the remote also points (LG's Magic Remote), reaching the game as ordinary pointer and
 	 * mouse events (hover, click with OK). Then let what the game has to pick be clicked too (large hit areas, a hover
-	 * highlight). false otherwise, and from hosts that don't say. Not the pointer() adapter, which makes a child's hand
-	 * the mouse.
+	 * highlight). Also true for a game whose manifest says "remoteCursor": true, when the arrows move a cursor: the SDK
+	 * makes the same pointer and mouse events from it (OK held: pointerdown … pointerup, then click), so a game written
+	 * for the pointer works with both. false otherwise, and from hosts that don't say. Not the pointer() adapter, which
+	 * makes a child's hand the mouse.
 	 */
 	readonly pointer: boolean;
+	/**
+	 * Whether savePicture can reach a phone now: true when the screen says a phone that saves pictures is linked (the
+	 * app; the web phone can't). It can change mid-game: listen to 'capabilities'. Hide or grey a "save" button while
+	 * it is false, and never make the children wait on it.
+	 */
+	readonly canSavePicture: boolean;
+	/**
+	 * Saves a picture on the family's phone, in its gallery (a drawing, the photo of a wall). source: a canvas (scaled
+	 * down to MAX_PICTURE_SIDE, 1920 px on its longer side, drawn on white and encoded as JPEG at quality 0.85, lower
+	 * if it would be over 3 MiB) or a data URL (data:image/jpeg or data:image/png, base64, sent as it is). title: a
+	 * name for it (up to 60 characters). Resolves with what became of it: 'sent' (the phone has it), 'unavailable' (no
+	 * phone that saves pictures: canSavePicture is false), 'too-big' (over 3 MiB), 'error' (a canvas that can't be read,
+	 * not an image, the link dropped, no answer in 2 minutes). Never rejects.
+	 *
+	 * Privacy: the picture goes only from the TV to the phone over their direct link (WebRTC, encrypted), never to a
+	 * server, and nothing else can be sent this way. If the phone can't save it (permission denied), Fabi Play tells the
+	 * parent on the phone: don't tell the children.
+	 *
+	 * @example
+	 * if (play.canSavePicture) await play.savePicture(canvas, { title: 'Our wall' })
+	 */
+	savePicture(source: PictureSource, opts?: {
+		title?: string;
+	}): Promise<PictureResult>;
+	/**
+	 * The screen's orientation when the game started: 'landscape' (width ≥ height; the TV, the tablet, and what older
+	 * hosts mean) or 'portrait' (a phone held upright, only for games whose manifest lists it in orientations). Use it
+	 * to choose a layout, but size everything from the real viewport (innerWidth × innerHeight): it is not updated if
+	 * the screen turns.
+	 */
+	readonly orientation: Orientation;
 	/** The screen's sound is off: start the game muted. */
 	readonly muted: boolean;
 	/** The players' age range: simpler rules for 3-5, scores and challenges for 9-12. */
@@ -873,8 +1066,8 @@ export interface Play {
 	/** Called when backdrop or view changes; returns a function that stops listening. */
 	onBackdrop(listener: (backdrop: Backdrop, view: BackdropView | null) => void): () => void;
 	/**
-	 * Listens to the host: 'frame', 'gesture', 'pause', 'resume', 'break-start', 'break-done', 'backdrop', 'turn'
-	 * (see Events). Returns a function that stops listening.
+	 * Listens to the host: 'frame', 'gesture', 'pause', 'resume', 'break-start', 'break-done', 'backdrop', 'turn',
+	 * 'capabilities', 'cursor' (see Events). Returns a function that stops listening.
 	 *
 	 * @example
 	 * const off = play.on('frame', (f) => (players = f.players))
@@ -923,6 +1116,14 @@ export interface FabiPlayGlobal extends Easy {
 	 */
 	readonly avatars: Readonly<Record<string, unknown>>;
 }
+/** connect()'s options. */
+export interface ConnectOptions {
+	/**
+	 * Where the remote's cursor events go ("remoteCursor": true): by default the page (domCursor()), null for nowhere
+	 * (the game reads the 'cursor' event itself). Tests pass their own.
+	 */
+	cursor?: CursorTarget | null;
+}
 /** The channel to the screen that embeds the game: the parent window, listening only to messages from it. */
 export declare const windowChannel: (win?: Window) => Channel;
 /**
@@ -937,7 +1138,7 @@ export declare const windowChannel: (win?: Window) => Channel;
  * play.on('gesture', ({ player, gesture }) => gesture === 'jump' && jump(player))
  * play.ready()
  */
-export declare function connect(channel?: Channel): Promise<Play>;
+export declare function connect(channel?: Channel, options?: ConnectOptions): Promise<Play>;
 
 
 

package/dist/index.js

@@ -1,20 +1,26 @@
 import {
   BodyInterpolator,
+  MAX_PICTURE_SIDE,
   NS,
+  PICTURE_JPEG_QUALITY,
   PROTOCOL_VERSION,
   __publicField,
+  checkPicture,
   defaultAvatarFor,
   drawAvatar,
   isAvatarId,
+  parseCursor,
   parseDeviceHint,
   parseGameStats,
+  parsePictureResult,
+  parsePictureTitle,
   parseTurnOrder,
   parseTurnPlayers,
   parseView,
   smoothBody,
   toScreen,
   wire
-} from "./chunks/chunk-GFNOIOSX.js";
+} from "./chunks/chunk-H3BKYVPL.js";
 
 // src/adapters.ts
 function muteDuringBreaks(play, win = window) {
@@ -210,6 +216,59 @@ function pointer(play, options = {}) {
     target.cursor(x, y, clicked ? 0 : progress);
   });
 }
+function domCursor(doc = document) {
+  const win = doc.defaultView;
+  const Pointer = win?.PointerEvent;
+  const Mouse = win?.MouseEvent ?? MouseEvent;
+  let over = null;
+  let pressed = null;
+  const fire = (el, type, x, y, buttons, related = null) => {
+    const init = { bubbles: true, cancelable: true, composed: true, view: win, clientX: x, clientY: y, screenX: x, screenY: y, button: 0, buttons, relatedTarget: related, pointerId: 1, pointerType: "mouse", isPrimary: true };
+    if (type.startsWith("pointer")) {
+      if (Pointer) el.dispatchEvent(new Pointer(type, init));
+    } else el.dispatchEvent(new Mouse(type, init));
+  };
+  return {
+    // The viewport (the game's frame), not the document, which may be taller.
+    size: () => ({ width: win?.innerWidth ?? doc.documentElement.clientWidth, height: win?.innerHeight ?? doc.documentElement.clientHeight }),
+    dispatch(type, x, y, buttons) {
+      const el = doc.elementFromPoint(x, y) ?? doc.body ?? doc.documentElement;
+      if (type === "pointermove" && el !== over) {
+        if (over?.isConnected) for (const t of ["pointerout", "mouseout"]) fire(over, t, x, y, buttons, el);
+        for (const t of ["pointerover", "mouseover"]) fire(el, t, x, y, buttons, over);
+        over = el;
+      }
+      if (type === "pointerdown") pressed = el;
+      if (type === "click") {
+        const same = pressed === el;
+        pressed = null;
+        if (!same) return;
+      }
+      fire(el, type, x, y, buttons);
+    }
+  };
+}
+function cursorDriver(target) {
+  let last = null;
+  const send = (types, x, y, buttons) => {
+    const { width, height } = target.size();
+    for (const t of types) target.dispatch(t, x * width, y * height, buttons);
+  };
+  return {
+    update(c) {
+      const was = last?.down ?? false;
+      if (!last || last.x !== c.x || last.y !== c.y) send(["pointermove", "mousemove"], c.x, c.y, was ? 1 : 0);
+      if (c.down && !was) send(["pointerdown", "mousedown"], c.x, c.y, 1);
+      if (!c.down && was) send(["pointerup", "mouseup", "click"], c.x, c.y, 0);
+      last = { x: c.x, y: c.y, down: c.down };
+    },
+    cancel() {
+      if (!last?.down) return;
+      send(["pointercancel", "mouseup"], last.x, last.y, 0);
+      last = { ...last, down: false };
+    }
+  };
+}
 
 // src/avatars.ts
 var frameTime = () => {
@@ -342,6 +401,7 @@ function easy(connecting) {
     p.on("break-done", (m) => emit("break-end", { shown: m.shown }));
     p.onBackdrop((backdrop, view) => emit("backdrop", { backdrop, view }));
     p.on("turn", (m) => emit("turn", { players: [...m.players] }));
+    p.on("capabilities", (m) => emit("capabilities", { pictures: m.pictures }));
     p.on("frame", (f) => {
       emit("players", { players: f.players });
       for (const pl of f.players) {
@@ -388,6 +448,13 @@ function easy(connecting) {
     get hasPointer() {
       return play?.pointer ?? false;
     },
+    get canSavePicture() {
+      return play?.canSavePicture ?? false;
+    },
+    savePicture: (source, opts) => new Promise((resolve) => withPlay((p) => void p.savePicture(source, opts).then(resolve))),
+    get muted() {
+      return play?.muted ?? false;
+    },
     get view() {
       return play?.view ?? null;
     },
@@ -402,7 +469,7 @@ function easy(connecting) {
   };
 }
 var none = Object.freeze([]);
-var startInfo = (p) => ({ ageRange: p.ageRange, players: p.players, locale: p.locale, mode: p.mode, backdrop: p.backdrop, view: p.view, device: p.device, turns: p.turns, input: p.input, pointer: p.pointer });
+var startInfo = (p) => ({ ageRange: p.ageRange, players: p.players, locale: p.locale, mode: p.mode, orientation: p.orientation, backdrop: p.backdrop, view: p.view, device: p.device, turns: p.turns, input: p.input, pointer: p.pointer, canSavePicture: p.canSavePicture, muted: p.muted });
 var playingNow = (p) => p.input === "remote" ? p.players[0] ?? 1 : 1;
 function endOf(p, score, last) {
   const now = playingNow(p);
@@ -411,6 +478,46 @@ function endOf(p, score, last) {
   return [...played.map((player) => ({ player, score: last.get(player) ?? 0, stars: 2 })), { player: now, score, stars: 2 }];
 }
 
+// src/picture.ts
+var QUALITIES = [PICTURE_JPEG_QUALITY, 0.7, 0.55];
+var SHRINK = 0.75;
+var MIN_SIDE = 320;
+function encodePicture(source) {
+  if (typeof source === "string") {
+    const checked = checkPicture(source);
+    return "ok" in checked ? { data: source } : { error: checked.error === "too-big" ? "too-big" : "error" };
+  }
+  try {
+    if (!source || typeof source.toDataURL !== "function") return { error: "error" };
+    const { width, height } = source;
+    if (!(width > 0 && height > 0)) return { error: "error" };
+    const doc = source.ownerDocument ?? document;
+    let scale = Math.min(1, MAX_PICTURE_SIDE / Math.max(width, height));
+    for (; ; ) {
+      const w = Math.max(1, Math.round(width * scale));
+      const h = Math.max(1, Math.round(height * scale));
+      const flat = doc.createElement("canvas");
+      flat.width = w;
+      flat.height = h;
+      const ctx = flat.getContext("2d");
+      if (!ctx) return { error: "error" };
+      ctx.fillStyle = "#fff";
+      ctx.fillRect(0, 0, w, h);
+      ctx.drawImage(source, 0, 0, w, h);
+      for (const q of QUALITIES) {
+        const data = flat.toDataURL("image/jpeg", q);
+        const checked = checkPicture(data);
+        if ("ok" in checked) return { data };
+        if (checked.error !== "too-big") return { error: "error" };
+      }
+      if (Math.max(w, h) * SHRINK < MIN_SIDE) return { error: "too-big" };
+      scale *= SHRINK;
+    }
+  } catch {
+    return { error: "error" };
+  }
+}
+
 // src/index.ts
 var windowChannel = (win = window) => ({
   post: (m) => win.parent.postMessage(m, "*"),
@@ -419,7 +526,8 @@ var windowChannel = (win = window) => ({
 });
 var INIT_TIMEOUT_MS = 1e4;
 var STATS_MS = 1e3;
-function connect(channel = windowChannel()) {
+var PICTURE_TIMEOUT_MS = 12e4;
+function connect(channel = windowChannel(), options = {}) {
   return new Promise((resolve, reject) => {
     const listeners = /* @__PURE__ */ new Map();
     const breaks = [];
@@ -431,6 +539,17 @@ function connect(channel = windowChannel()) {
     let input = "body";
     let players = Object.freeze([]);
     let turns = players;
+    let pictures = false;
+    let pictureId = 0;
+    const pictureWaits = /* @__PURE__ */ new Map();
+    let cursor;
+    const cursorTarget = () => {
+      if (cursor === void 0) {
+        const target = options.cursor !== void 0 ? options.cursor : typeof document !== "undefined" ? domCursor() : null;
+        cursor = target ? cursorDriver(target) : null;
+      }
+      return cursor;
+    };
     const backdropListeners = /* @__PURE__ */ new Set();
     const avatars = new AvatarBook();
     const drawAvatar2 = avatarDrawer(avatars, () => ({ view }));
@@ -451,6 +570,7 @@ function connect(channel = windowChannel()) {
         const device = parseDeviceHint(m.device) ?? null;
         input = m.input === "remote" ? "remote" : "body";
         const pointer2 = input === "remote" && m.pointer === true;
+        pictures = m.pictures === true;
         players = Object.freeze(Array.isArray(m.players) ? [...m.players] : []);
         const order = input === "remote" && players.length === 1 ? parseTurnOrder(m.turns) : void 0;
         turns = Object.freeze(order && order[0] === players[0] ? order : [...players]);
@@ -474,6 +594,8 @@ function connect(channel = windowChannel()) {
           input,
           pointer: pointer2,
           muted: m.muted,
+          // Hosts before orientations don't send it: landscape.
+          orientation: m.orientation === "portrait" ? "portrait" : "landscape",
           ageRange: m.ageRange ?? "6-8",
           get backdrop() {
             return backdrop;
@@ -505,7 +627,28 @@ function connect(channel = windowChannel()) {
             breaks.push({ reason, done });
             channel.post(wire({ type: "break", reason }));
           }),
-          end: (scores) => channel.post(wire({ type: "end", scores }))
+          end: (scores) => channel.post(wire({ type: "end", scores })),
+          get canSavePicture() {
+            return pictures;
+          },
+          savePicture: async (source, opts) => {
+            if (!pictures) return "unavailable";
+            const encoded = encodePicture(source);
+            if ("error" in encoded) return encoded.error;
+            const id = ++pictureId;
+            const title = parsePictureTitle(opts?.title);
+            return new Promise((done) => {
+              const timer2 = setTimeout(() => finish("error"), PICTURE_TIMEOUT_MS);
+              timer2.unref?.();
+              const finish = (r) => {
+                clearTimeout(timer2);
+                pictureWaits.delete(id);
+                done(r);
+              };
+              pictureWaits.set(id, finish);
+              channel.post(wire({ type: "picture", data: encoded.data, id, ...title ? { title } : {} }));
+            });
+          }
         });
       } else if (!started) return;
       else {
@@ -528,6 +671,23 @@ function connect(channel = windowChannel()) {
           players = Object.freeze(next);
           message = { type: "turn", players: [...next] };
         }
+        if (m.type === "picture-result") {
+          const r = parsePictureResult(m);
+          if (r?.id !== void 0) pictureWaits.get(r.id)?.(r.result);
+          return;
+        }
+        if (m.type === "capabilities") {
+          if (typeof m.pictures !== "boolean" || m.pictures === pictures) return;
+          pictures = m.pictures;
+          message = { type: "capabilities", pictures };
+        }
+        if (m.type === "cursor") {
+          const c = input === "remote" ? parseCursor(m) : void 0;
+          if (!c) return;
+          message = c;
+          cursorTarget()?.update(c);
+        }
+        if (m.type === "pause" || m.type === "break-start" || m.type === "turn") cursor?.cancel();
         if (m.type === "break-start") inBreak = breaks.length > 0;
         for (const l of listeners.get(m.type) ?? []) l(message);
         if (m.type === "break-done") {
@@ -544,7 +704,9 @@ export {
   DEFAULT_KEYS,
   avatarDrawer,
   connect,
+  cursorDriver,
   defaultBox,
+  domCursor,
   domKeys,
   domPointer,
   easy,

package/dist/integrity.json

@@ -1,12 +1,12 @@
 {
   "package": "@fabi-play/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "algorithm": "sha384",
   "files": {
-    "fabi-play.js": "sha384-GQRWKvHJbNMap9RaUmZb53cutIjP+4znP6K2qV33TDz7CuB8tUEKWb8b6rIr0kDZ",
-    "fabi-play.umd.js": "sha384-GARYP8mvinQoV9l0yqHQUr6tz8dSGhHtBVCJvJT3vgzbaeheds0DbMwb4TORJkE7",
-    "fabi-play.umd.min.js": "sha384-EsqeNcQaqmkU5zfOtErKZwQdxoWhm8M5t7ra10U0o0IKRHQw37CyNC5BpLogDSHw",
-    "fabi-play.d.ts": "sha384-D99Rlv+HHC7+UQlLqOJreHqt6JDVMzzxuJbXIBVmB4I+WFER2ELU/ESCiX5qT9T6",
-    "fabi-play.schema.json": "sha384-R70ay7ddz0QDzU+YN5CiyiVSeCDdoGymdVNbbSBPUOQgDpAh4ajinUGzRLa5qq7y"
+    "fabi-play.js": "sha384-JCeReswB7As8HjTU/NrUm65v4hdP6h+MeBvkXSOhbepLjp0ZRDwO971vvtz5c7nE",
+    "fabi-play.umd.js": "sha384-Z0PlTJwDDUykoewaUvtN9zMAajhdAGUChI0QHPAKEr9OY2skgcSpKdDHyFAAzWbO",
+    "fabi-play.umd.min.js": "sha384-CwK92hvLuW7J5QrbkM8YTsovrVOSfIeNXWgrnASrqAv0BvvfeWEvUCbsyLiuw5gk",
+    "fabi-play.d.ts": "sha384-r4+XUf2qkT+nZ5RSkQooR7IZUr/Y4F9iZGwx9lB1rHehmqytu7zPMEsQWW6rIHta",
+    "fabi-play.schema.json": "sha384-MzT9DYjL6d80Ff+4iZQFbrQVpg7q02ok5Bzkb2UKshUStaFZocty+JxuzLHXXheR"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabi-play/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "What a game imports: players, movements and the end of the game, from inside its sandboxed frame.",
   "keywords": [
     "fabi-play",
@@ -36,8 +36,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@fabi-play/avatars": "^0.3.0",
-    "@fabi-play/protocol": "^0.3.0",
+    "@fabi-play/avatars": "^0.5.0",
+    "@fabi-play/protocol": "^0.5.0",
     "dts-bundle-generator": "9.5.1",
     "esbuild": "0.28.2",
     "tsx": "4.23.15",