@oasiz/sdk 1.8.4 → 1.8.6

package/README.md

@@ -167,6 +167,49 @@ or `southwest`.
 `backflip` is not directional, so `getJibbleAnimationId("backflip", "left")`
 still returns `backflip`.
 
+#### Local browser sample atlas
+
+Inside the Oasiz app, `oasiz.getPlayerCharacter()` returns the authenticated
+player's real character atlas. On `localhost` or `file://` without the app
+bridge, it first fetches an Oasiz-owned real sample atlas from
+`https://api.oasiz.ai/api/sdk/sample-character`, so browser games can test
+sprite loading, atlas slicing, and animation lookup before publishing.
+
+The platform sample is generated by the same backend/R2 atlas pipeline as real
+characters, but it is not a user character and it does not expose user id,
+layer config, or personal data. If the endpoint is unavailable, the SDK uses a
+tiny generated atlas as a resilience fallback unless disabled.
+
+```ts
+const character = await oasiz.getPlayerCharacter();
+
+// In Oasiz app: the real signed-in player's character.
+// On localhost without the app bridge: "Oasiz Sample Jibble".
+// On non-local pages without the app bridge: null.
+```
+
+Use the options when you need explicit behavior:
+
+```ts
+// Keep the old "missing bridge means null" behavior.
+const characterOrNull = await oasiz.getPlayerCharacter({ localFallback: false });
+
+// Force the sample atlas in a browser test harness.
+const sampleCharacter = await oasiz.getPlayerCharacter({ localFallback: true });
+
+// Strict mode: require the platform-generated sample, with no generated backup.
+const platformOnlySample = await oasiz.getPlayerCharacter({
+  localFallback: true,
+  generatedFallback: false,
+});
+
+// Override the sample endpoint when testing against staging.
+const stagingSample = await oasiz.getPlayerCharacter({
+  localFallback: true,
+  sampleCharacterUrl: "https://staging-api.oasiz.ai/api/sdk/sample-character",
+});
+```
+
 #### HTML5 / TypeScript
 
 ```ts

package/dist/index.cjs

@@ -37,6 +37,8 @@ __export(index_exports, {
   getPlayerName: () => getPlayerName,
   getRoomCode: () => getRoomCode,
   getSafeAreaTop: () => getSafeAreaTop,
+  getSamplePlayerCharacter: () => getSamplePlayerCharacter,
+  getSampleTextureAtlas: () => getSampleTextureAtlas,
   getViewportInsets: () => getViewportInsets,
   leaveGame: () => leaveGame,
   loadGameState: () => loadGameState,
@@ -1444,65 +1446,6 @@ function enableAppSimulator(options = {}) {
   return handle;
 }
 
-// src/character.ts
-function isDevelopment2() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow2() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function warnMissingBridge2(methodName) {
-  if (isDevelopment2()) {
-    console.warn(
-      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-async function getPlayerCharacter() {
-  const bridge = getBridgeWindow2();
-  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
-    warnMissingBridge2("getPlayerCharacter");
-    return null;
-  }
-  try {
-    const result = await bridge.__oasizGetPlayerCharacter();
-    return result ?? null;
-  } catch (error) {
-    if (isDevelopment2()) {
-      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
-    }
-    return null;
-  }
-}
-
-// src/haptics.ts
-function isDevelopment3() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow3() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function triggerHaptic(type) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.triggerHaptic === "function") {
-    bridge.triggerHaptic(type);
-    return;
-  }
-  if (isDevelopment3()) {
-    console.warn(
-      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-
 // src/jibble.ts
 var JIBBLE_DIRECTIONS = [
   "n",
@@ -1603,6 +1546,282 @@ function getJibbleAnimationId(action, direction = "front") {
   return `${action}_${normalizeJibbleDirection(direction)}`;
 }
 
+// src/sample-character.ts
+var FRAME_SIZE = 32;
+var COLUMNS = 8;
+var WALK_FRAME_COUNT = 2;
+var BACKFLIP_FRAME_COUNT = 4;
+var COLORS = [
+  "#2563eb",
+  "#7c3aed",
+  "#db2777",
+  "#ea580c",
+  "#16a34a",
+  "#0891b2",
+  "#4f46e5",
+  "#be123c"
+];
+var IDLE_FRAME_NAMES = JIBBLE_DIRECTIONS.map((direction) => `idle_${direction}`);
+var WALK_FRAME_NAMES = JIBBLE_DIRECTIONS.flatMap(
+  (direction) => Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`)
+);
+var BACKFLIP_FRAME_NAMES = Array.from(
+  { length: BACKFLIP_FRAME_COUNT },
+  (_, index) => `backflip_${index}`
+);
+var SAMPLE_FRAME_NAMES = [
+  ...IDLE_FRAME_NAMES,
+  ...WALK_FRAME_NAMES,
+  ...BACKFLIP_FRAME_NAMES
+];
+var IMAGE_WIDTH = COLUMNS * FRAME_SIZE;
+var IMAGE_HEIGHT = Math.ceil(SAMPLE_FRAME_NAMES.length / COLUMNS) * FRAME_SIZE;
+function getFrameRect(index) {
+  return {
+    x: index % COLUMNS * FRAME_SIZE,
+    y: Math.floor(index / COLUMNS) * FRAME_SIZE,
+    width: FRAME_SIZE,
+    height: FRAME_SIZE
+  };
+}
+function createFrame(name, index) {
+  return {
+    name,
+    ...getFrameRect(index)
+  };
+}
+function getFrameLabel(name) {
+  return name.replace(/^idle_/, "i ").replace(/^walk_/, "w ").replace(/^backflip_/, "flip ");
+}
+function createSvgDataUrl() {
+  const cells = SAMPLE_FRAME_NAMES.map((name, index) => {
+    const { x, y } = getFrameRect(index);
+    const color = COLORS[index % COLORS.length];
+    const label = getFrameLabel(name);
+    return [
+      `<rect x="${x}" y="${y}" width="${FRAME_SIZE}" height="${FRAME_SIZE}" fill="${color}"/>`,
+      `<rect x="${x + 1}" y="${y + 1}" width="${FRAME_SIZE - 2}" height="${FRAME_SIZE - 2}" fill="none" stroke="#ffffff" stroke-opacity="0.35"/>`,
+      `<circle cx="${x + 16}" cy="${y + 11}" r="5" fill="#ffffff" fill-opacity="0.92"/>`,
+      `<rect x="${x + 12}" y="${y + 17}" width="8" height="7" rx="2" fill="#ffffff" fill-opacity="0.86"/>`,
+      `<text x="${x + 16}" y="${y + 30}" text-anchor="middle" font-family="monospace" font-size="5" fill="#ffffff">${label}</text>`
+    ].join("");
+  }).join("");
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" viewBox="0 0 ${IMAGE_WIDTH} ${IMAGE_HEIGHT}">`,
+    `<rect width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" fill="#111827"/>`,
+    cells,
+    "</svg>"
+  ].join("");
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+function createDirectionalAnimation(animationId, role, direction, frames, frameRate) {
+  return {
+    animationId,
+    role,
+    group: "jibble",
+    direction,
+    frameRate,
+    frames,
+    facingFrameMap: null
+  };
+}
+var SAMPLE_TEXTURE_ATLAS = {
+  imageUrl: createSvgDataUrl(),
+  imageWidth: IMAGE_WIDTH,
+  imageHeight: IMAGE_HEIGHT,
+  frames: SAMPLE_FRAME_NAMES.map(createFrame),
+  animations: [
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("idle", direction),
+        "idle",
+        direction,
+        [`idle_${direction}`],
+        1
+      )
+    ),
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("walk", direction),
+        "walk",
+        direction,
+        Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`),
+        8
+      )
+    ),
+    {
+      animationId: JIBBLE_ANIMATION.Backflip,
+      role: "action",
+      group: "jibble",
+      direction: null,
+      frameRate: 10,
+      frames: BACKFLIP_FRAME_NAMES,
+      facingFrameMap: null
+    }
+  ]
+};
+function cloneTextureAtlas(atlas) {
+  return {
+    ...atlas,
+    frames: atlas.frames.map((frame) => ({ ...frame })),
+    animations: atlas.animations.map((animation) => ({
+      ...animation,
+      frames: [...animation.frames],
+      facingFrameMap: animation.facingFrameMap ? { ...animation.facingFrameMap } : null
+    }))
+  };
+}
+function getSampleTextureAtlas() {
+  return cloneTextureAtlas(SAMPLE_TEXTURE_ATLAS);
+}
+function getSamplePlayerCharacter() {
+  return {
+    characterName: "SDK Sample Jibble",
+    baseCharacterId: "sdk-sample-jibble",
+    compositionCode: "sdk-sample-jibble-atlas-v1",
+    textureAtlas: getSampleTextureAtlas(),
+    editorTextureAtlas: getSampleTextureAtlas()
+  };
+}
+
+// src/character.ts
+var DEFAULT_SAMPLE_CHARACTER_URL = "https://api.oasiz.ai/api/sdk/sample-character";
+var DEFAULT_SAMPLE_FETCH_TIMEOUT_MS = 1500;
+function isDevelopment2() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow2() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function isLocalHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function shouldUseLocalFallback(bridge, localFallback) {
+  if (localFallback === true) {
+    return true;
+  }
+  if (localFallback === false) {
+    return false;
+  }
+  const location = bridge?.location;
+  if (!location) {
+    return false;
+  }
+  return location.protocol === "file:" || isLocalHostname(location.hostname);
+}
+function warnMissingBridge2(methodName, usingFallback) {
+  if (isDevelopment2()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. " + (usingFallback ? "Using the SDK sample character atlas for local development." : "This is expected in local development.")
+    );
+  }
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTextureAtlas(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return typeof value.imageUrl === "string" && typeof value.imageWidth === "number" && Number.isFinite(value.imageWidth) && typeof value.imageHeight === "number" && Number.isFinite(value.imageHeight) && Array.isArray(value.frames) && Array.isArray(value.animations);
+}
+function isPlayerCharacter(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return (typeof value.characterName === "string" || value.characterName === null) && typeof value.baseCharacterId === "string" && typeof value.compositionCode === "string" && isTextureAtlas(value.textureAtlas) && (value.editorTextureAtlas === null || isTextureAtlas(value.editorTextureAtlas));
+}
+function unwrapSampleCharacterResponse(payload) {
+  if (isPlayerCharacter(payload)) {
+    return payload;
+  }
+  if (isRecord2(payload) && isPlayerCharacter(payload.character)) {
+    return payload.character;
+  }
+  return null;
+}
+async function fetchPlatformSampleCharacter(options) {
+  if (typeof fetch !== "function") {
+    return null;
+  }
+  const timeoutMs = options.sampleFetchTimeoutMs ?? DEFAULT_SAMPLE_FETCH_TIMEOUT_MS;
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timeout = controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+  try {
+    const response = await fetch(
+      options.sampleCharacterUrl ?? DEFAULT_SAMPLE_CHARACTER_URL,
+      {
+        signal: controller?.signal
+      }
+    );
+    if (!response.ok) {
+      return null;
+    }
+    return unwrapSampleCharacterResponse(await response.json());
+  } catch {
+    return null;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    if (!useLocalFallback) {
+      return null;
+    }
+    const platformSample = await fetchPlatformSampleCharacter(options);
+    if (platformSample) {
+      return platformSample;
+    }
+    return options.generatedFallback === false ? null : getSamplePlayerCharacter();
+  }
+  try {
+    const result = await bridge.__oasizGetPlayerCharacter();
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment2()) {
+      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
+    }
+    return null;
+  }
+}
+
+// src/haptics.ts
+function isDevelopment3() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow3() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function triggerHaptic(type) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.triggerHaptic === "function") {
+    bridge.triggerHaptic(type);
+    return;
+  }
+  if (isDevelopment3()) {
+    console.warn(
+      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+
 // src/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -2830,7 +3049,7 @@ function warnMissingBridge7(methodName) {
     );
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber(value) {
@@ -2999,11 +3218,11 @@ function callBridgeFunction(bridge, name) {
   }
 }
 function readInsetObjectValue(value, side, group) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return void 0;
   }
   if (group) {
-    return isRecord2(value[group]) ? value[group][side] : void 0;
+    return isRecord3(value[group]) ? value[group][side] : void 0;
   }
   return value[side];
 }
@@ -3140,7 +3359,7 @@ function getBridgeWindow10() {
   }
   return window;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber2(value) {
@@ -3206,7 +3425,7 @@ function normalizeMetric(value) {
     }
     return void 0;
   }
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const fpsCandidate = firstDefined2(
@@ -3456,6 +3675,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3518,6 +3739,8 @@ var oasiz = {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   getViewportInsets,
   leaveGame,
   loadGameState,

package/dist/index.d.cts

@@ -220,13 +220,35 @@ interface ScoreEditResult {
     normalizedScore: number | null;
 }
 
+interface GetPlayerCharacterOptions {
+    /**
+     * Controls the SDK sample character returned when the Oasiz app bridge is
+     * missing. `"auto"` returns the sample on localhost/file URLs only.
+     */
+    localFallback?: boolean | "auto";
+    /**
+     * Public endpoint used for the real platform-generated local sample atlas.
+     */
+    sampleCharacterUrl?: string;
+    /**
+     * Timeout for the public sample endpoint before falling back locally.
+     */
+    sampleFetchTimeoutMs?: number;
+    /**
+     * When true, a tiny generated atlas is used if the platform sample endpoint
+     * is unavailable. Set false for strict platform-sample-only local testing.
+     */
+    generatedFallback?: boolean;
+}
 /**
  * Fetch the authenticated player's character, including a TexturePacker /
  * Phaser-style texture atlas describing the baked sprite image.
  *
  * Returns:
  *   - `null` when the user has no character composition yet, OR
- *   - `null` when the host bridge is unavailable (local dev / unauthenticated)
+ *   - a sample character atlas when the host bridge is unavailable on a local
+ *     browser URL (`localhost` / `file://`), OR
+ *   - `null` when the host bridge is unavailable and local fallback is disabled
  *
  * The host transparently caches and proxies to `GET /api/sdk/me/character`,
  * so calling this multiple times in a session is cheap. The returned
@@ -245,7 +267,7 @@ interface ScoreEditResult {
  *     ),
  *   });
  */
-declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
+declare function getPlayerCharacter(options?: GetPlayerCharacterOptions): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -381,6 +403,9 @@ declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
 
+declare function getSampleTextureAtlas(): TextureAtlas;
+declare function getSamplePlayerCharacter(): PlayerCharacter;
+
 declare const oasiz: {
     submitScore: typeof submitScore;
     enableAppSimulator: typeof enableAppSimulator;
@@ -413,6 +438,8 @@ declare const oasiz: {
     addScore: typeof addScore;
     setScore: typeof setScore;
     getPlayerCharacter: typeof getPlayerCharacter;
+    getSamplePlayerCharacter: typeof getSamplePlayerCharacter;
+    getSampleTextureAtlas: typeof getSampleTextureAtlas;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -441,4 +468,4 @@ declare const oasiz: {
     readonly graphicsPerformance: GraphicsPerformanceMetric;
 };
 
-export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GetPlayerCharacterOptions, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getSamplePlayerCharacter, getSampleTextureAtlas, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.d.ts

@@ -220,13 +220,35 @@ interface ScoreEditResult {
     normalizedScore: number | null;
 }
 
+interface GetPlayerCharacterOptions {
+    /**
+     * Controls the SDK sample character returned when the Oasiz app bridge is
+     * missing. `"auto"` returns the sample on localhost/file URLs only.
+     */
+    localFallback?: boolean | "auto";
+    /**
+     * Public endpoint used for the real platform-generated local sample atlas.
+     */
+    sampleCharacterUrl?: string;
+    /**
+     * Timeout for the public sample endpoint before falling back locally.
+     */
+    sampleFetchTimeoutMs?: number;
+    /**
+     * When true, a tiny generated atlas is used if the platform sample endpoint
+     * is unavailable. Set false for strict platform-sample-only local testing.
+     */
+    generatedFallback?: boolean;
+}
 /**
  * Fetch the authenticated player's character, including a TexturePacker /
  * Phaser-style texture atlas describing the baked sprite image.
  *
  * Returns:
  *   - `null` when the user has no character composition yet, OR
- *   - `null` when the host bridge is unavailable (local dev / unauthenticated)
+ *   - a sample character atlas when the host bridge is unavailable on a local
+ *     browser URL (`localhost` / `file://`), OR
+ *   - `null` when the host bridge is unavailable and local fallback is disabled
  *
  * The host transparently caches and proxies to `GET /api/sdk/me/character`,
  * so calling this multiple times in a session is cheap. The returned
@@ -245,7 +267,7 @@ interface ScoreEditResult {
  *     ),
  *   });
  */
-declare function getPlayerCharacter(): Promise<PlayerCharacter | null>;
+declare function getPlayerCharacter(options?: GetPlayerCharacterOptions): Promise<PlayerCharacter | null>;
 
 declare function triggerHaptic(type: HapticType): void;
 
@@ -381,6 +403,9 @@ declare function loadGameState(): GameState;
 declare function saveGameState(state: GameState): void;
 declare function flushGameState(): void;
 
+declare function getSampleTextureAtlas(): TextureAtlas;
+declare function getSamplePlayerCharacter(): PlayerCharacter;
+
 declare const oasiz: {
     submitScore: typeof submitScore;
     enableAppSimulator: typeof enableAppSimulator;
@@ -413,6 +438,8 @@ declare const oasiz: {
     addScore: typeof addScore;
     setScore: typeof setScore;
     getPlayerCharacter: typeof getPlayerCharacter;
+    getSamplePlayerCharacter: typeof getSamplePlayerCharacter;
+    getSampleTextureAtlas: typeof getSampleTextureAtlas;
     share: typeof share;
     triggerHaptic: typeof triggerHaptic;
     enableLogOverlay: typeof enableLogOverlay;
@@ -441,4 +468,4 @@ declare const oasiz: {
     readonly graphicsPerformance: GraphicsPerformanceMetric;
 };
 
-export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };
+export { type AppSimulatorDevice, type AppSimulatorDeviceName, type AppSimulatorHandle, type AppSimulatorOptions, type AppSimulatorOrientation, type BackButtonTestingHandle, type BackButtonTestingOptions, type FacingFrameMap, type GameState, type GetPlayerCharacterOptions, type GraphicsPerformanceMetric, type GraphicsPerformanceTier, type HapticType, JIBBLE_ANIMATION, JIBBLE_ANIMATION_IDS, JIBBLE_DIRECTIONS, type JibbleAnimationAction, type JibbleAnimationId, type JibbleDirectionCode, type JibbleFacingDirection, type LogOverlayEntry, type LogOverlayHandle, type LogOverlayLevel, type LogOverlayOptions, type PlayerCharacter, type ScoreEditResult, type ShareRequest, type ShareRoomCodeOptions, type TextureAtlas, type TextureAtlasAnimation, type TextureAtlasFrame, type Unsubscribe, type ViewportInsetEdges, type ViewportInsetSide, type ViewportInsets, addScore, enableAppSimulator, enableBackButtonTesting, enableLogOverlay, flushGameState, getGameId, getGraphicsPerformance, getJibbleAnimationId, getPlayerAvatar, getPlayerCharacter, getPlayerId, getPlayerName, getRoomCode, getSafeAreaTop, getSamplePlayerCharacter, getSampleTextureAtlas, getViewportInsets, leaveGame, loadGameState, normalizeJibbleDirection, oasiz, onBackButton, onLeaveGame, onPause, onResume, openInviteModal, saveGameState, setLeaderboardVisible, setScore, share, shareRoomCode, submitScore, triggerHaptic };

package/dist/index.js

@@ -1385,65 +1385,6 @@ function enableAppSimulator(options = {}) {
   return handle;
 }
 
-// src/character.ts
-function isDevelopment2() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow2() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function warnMissingBridge2(methodName) {
-  if (isDevelopment2()) {
-    console.warn(
-      "[oasiz/sdk] " + methodName + " bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-async function getPlayerCharacter() {
-  const bridge = getBridgeWindow2();
-  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
-    warnMissingBridge2("getPlayerCharacter");
-    return null;
-  }
-  try {
-    const result = await bridge.__oasizGetPlayerCharacter();
-    return result ?? null;
-  } catch (error) {
-    if (isDevelopment2()) {
-      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
-    }
-    return null;
-  }
-}
-
-// src/haptics.ts
-function isDevelopment3() {
-  const nodeEnv = globalThis.process?.env?.NODE_ENV;
-  return nodeEnv !== "production";
-}
-function getBridgeWindow3() {
-  if (typeof window === "undefined") {
-    return void 0;
-  }
-  return window;
-}
-function triggerHaptic(type) {
-  const bridge = getBridgeWindow3();
-  if (typeof bridge?.triggerHaptic === "function") {
-    bridge.triggerHaptic(type);
-    return;
-  }
-  if (isDevelopment3()) {
-    console.warn(
-      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
-    );
-  }
-}
-
 // src/jibble.ts
 var JIBBLE_DIRECTIONS = [
   "n",
@@ -1544,6 +1485,282 @@ function getJibbleAnimationId(action, direction = "front") {
   return `${action}_${normalizeJibbleDirection(direction)}`;
 }
 
+// src/sample-character.ts
+var FRAME_SIZE = 32;
+var COLUMNS = 8;
+var WALK_FRAME_COUNT = 2;
+var BACKFLIP_FRAME_COUNT = 4;
+var COLORS = [
+  "#2563eb",
+  "#7c3aed",
+  "#db2777",
+  "#ea580c",
+  "#16a34a",
+  "#0891b2",
+  "#4f46e5",
+  "#be123c"
+];
+var IDLE_FRAME_NAMES = JIBBLE_DIRECTIONS.map((direction) => `idle_${direction}`);
+var WALK_FRAME_NAMES = JIBBLE_DIRECTIONS.flatMap(
+  (direction) => Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`)
+);
+var BACKFLIP_FRAME_NAMES = Array.from(
+  { length: BACKFLIP_FRAME_COUNT },
+  (_, index) => `backflip_${index}`
+);
+var SAMPLE_FRAME_NAMES = [
+  ...IDLE_FRAME_NAMES,
+  ...WALK_FRAME_NAMES,
+  ...BACKFLIP_FRAME_NAMES
+];
+var IMAGE_WIDTH = COLUMNS * FRAME_SIZE;
+var IMAGE_HEIGHT = Math.ceil(SAMPLE_FRAME_NAMES.length / COLUMNS) * FRAME_SIZE;
+function getFrameRect(index) {
+  return {
+    x: index % COLUMNS * FRAME_SIZE,
+    y: Math.floor(index / COLUMNS) * FRAME_SIZE,
+    width: FRAME_SIZE,
+    height: FRAME_SIZE
+  };
+}
+function createFrame(name, index) {
+  return {
+    name,
+    ...getFrameRect(index)
+  };
+}
+function getFrameLabel(name) {
+  return name.replace(/^idle_/, "i ").replace(/^walk_/, "w ").replace(/^backflip_/, "flip ");
+}
+function createSvgDataUrl() {
+  const cells = SAMPLE_FRAME_NAMES.map((name, index) => {
+    const { x, y } = getFrameRect(index);
+    const color = COLORS[index % COLORS.length];
+    const label = getFrameLabel(name);
+    return [
+      `<rect x="${x}" y="${y}" width="${FRAME_SIZE}" height="${FRAME_SIZE}" fill="${color}"/>`,
+      `<rect x="${x + 1}" y="${y + 1}" width="${FRAME_SIZE - 2}" height="${FRAME_SIZE - 2}" fill="none" stroke="#ffffff" stroke-opacity="0.35"/>`,
+      `<circle cx="${x + 16}" cy="${y + 11}" r="5" fill="#ffffff" fill-opacity="0.92"/>`,
+      `<rect x="${x + 12}" y="${y + 17}" width="8" height="7" rx="2" fill="#ffffff" fill-opacity="0.86"/>`,
+      `<text x="${x + 16}" y="${y + 30}" text-anchor="middle" font-family="monospace" font-size="5" fill="#ffffff">${label}</text>`
+    ].join("");
+  }).join("");
+  const svg = [
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" viewBox="0 0 ${IMAGE_WIDTH} ${IMAGE_HEIGHT}">`,
+    `<rect width="${IMAGE_WIDTH}" height="${IMAGE_HEIGHT}" fill="#111827"/>`,
+    cells,
+    "</svg>"
+  ].join("");
+  return `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+}
+function createDirectionalAnimation(animationId, role, direction, frames, frameRate) {
+  return {
+    animationId,
+    role,
+    group: "jibble",
+    direction,
+    frameRate,
+    frames,
+    facingFrameMap: null
+  };
+}
+var SAMPLE_TEXTURE_ATLAS = {
+  imageUrl: createSvgDataUrl(),
+  imageWidth: IMAGE_WIDTH,
+  imageHeight: IMAGE_HEIGHT,
+  frames: SAMPLE_FRAME_NAMES.map(createFrame),
+  animations: [
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("idle", direction),
+        "idle",
+        direction,
+        [`idle_${direction}`],
+        1
+      )
+    ),
+    ...JIBBLE_DIRECTIONS.map(
+      (direction) => createDirectionalAnimation(
+        getJibbleAnimationId("walk", direction),
+        "walk",
+        direction,
+        Array.from({ length: WALK_FRAME_COUNT }, (_, index) => `walk_${direction}_${index}`),
+        8
+      )
+    ),
+    {
+      animationId: JIBBLE_ANIMATION.Backflip,
+      role: "action",
+      group: "jibble",
+      direction: null,
+      frameRate: 10,
+      frames: BACKFLIP_FRAME_NAMES,
+      facingFrameMap: null
+    }
+  ]
+};
+function cloneTextureAtlas(atlas) {
+  return {
+    ...atlas,
+    frames: atlas.frames.map((frame) => ({ ...frame })),
+    animations: atlas.animations.map((animation) => ({
+      ...animation,
+      frames: [...animation.frames],
+      facingFrameMap: animation.facingFrameMap ? { ...animation.facingFrameMap } : null
+    }))
+  };
+}
+function getSampleTextureAtlas() {
+  return cloneTextureAtlas(SAMPLE_TEXTURE_ATLAS);
+}
+function getSamplePlayerCharacter() {
+  return {
+    characterName: "SDK Sample Jibble",
+    baseCharacterId: "sdk-sample-jibble",
+    compositionCode: "sdk-sample-jibble-atlas-v1",
+    textureAtlas: getSampleTextureAtlas(),
+    editorTextureAtlas: getSampleTextureAtlas()
+  };
+}
+
+// src/character.ts
+var DEFAULT_SAMPLE_CHARACTER_URL = "https://api.oasiz.ai/api/sdk/sample-character";
+var DEFAULT_SAMPLE_FETCH_TIMEOUT_MS = 1500;
+function isDevelopment2() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow2() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function isLocalHostname(hostname) {
+  return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "0.0.0.0" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+function shouldUseLocalFallback(bridge, localFallback) {
+  if (localFallback === true) {
+    return true;
+  }
+  if (localFallback === false) {
+    return false;
+  }
+  const location = bridge?.location;
+  if (!location) {
+    return false;
+  }
+  return location.protocol === "file:" || isLocalHostname(location.hostname);
+}
+function warnMissingBridge2(methodName, usingFallback) {
+  if (isDevelopment2()) {
+    console.warn(
+      "[oasiz/sdk] " + methodName + " bridge is unavailable. " + (usingFallback ? "Using the SDK sample character atlas for local development." : "This is expected in local development.")
+    );
+  }
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTextureAtlas(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return typeof value.imageUrl === "string" && typeof value.imageWidth === "number" && Number.isFinite(value.imageWidth) && typeof value.imageHeight === "number" && Number.isFinite(value.imageHeight) && Array.isArray(value.frames) && Array.isArray(value.animations);
+}
+function isPlayerCharacter(value) {
+  if (!isRecord2(value)) {
+    return false;
+  }
+  return (typeof value.characterName === "string" || value.characterName === null) && typeof value.baseCharacterId === "string" && typeof value.compositionCode === "string" && isTextureAtlas(value.textureAtlas) && (value.editorTextureAtlas === null || isTextureAtlas(value.editorTextureAtlas));
+}
+function unwrapSampleCharacterResponse(payload) {
+  if (isPlayerCharacter(payload)) {
+    return payload;
+  }
+  if (isRecord2(payload) && isPlayerCharacter(payload.character)) {
+    return payload.character;
+  }
+  return null;
+}
+async function fetchPlatformSampleCharacter(options) {
+  if (typeof fetch !== "function") {
+    return null;
+  }
+  const timeoutMs = options.sampleFetchTimeoutMs ?? DEFAULT_SAMPLE_FETCH_TIMEOUT_MS;
+  const controller = typeof AbortController === "function" ? new AbortController() : null;
+  const timeout = controller && timeoutMs > 0 ? setTimeout(() => controller.abort(), timeoutMs) : void 0;
+  try {
+    const response = await fetch(
+      options.sampleCharacterUrl ?? DEFAULT_SAMPLE_CHARACTER_URL,
+      {
+        signal: controller?.signal
+      }
+    );
+    if (!response.ok) {
+      return null;
+    }
+    return unwrapSampleCharacterResponse(await response.json());
+  } catch {
+    return null;
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    if (!useLocalFallback) {
+      return null;
+    }
+    const platformSample = await fetchPlatformSampleCharacter(options);
+    if (platformSample) {
+      return platformSample;
+    }
+    return options.generatedFallback === false ? null : getSamplePlayerCharacter();
+  }
+  try {
+    const result = await bridge.__oasizGetPlayerCharacter();
+    return result ?? null;
+  } catch (error) {
+    if (isDevelopment2()) {
+      console.error("[oasiz/sdk] getPlayerCharacter failed:", error);
+    }
+    return null;
+  }
+}
+
+// src/haptics.ts
+function isDevelopment3() {
+  const nodeEnv = globalThis.process?.env?.NODE_ENV;
+  return nodeEnv !== "production";
+}
+function getBridgeWindow3() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  return window;
+}
+function triggerHaptic(type) {
+  const bridge = getBridgeWindow3();
+  if (typeof bridge?.triggerHaptic === "function") {
+    bridge.triggerHaptic(type);
+    return;
+  }
+  if (isDevelopment3()) {
+    console.warn(
+      "[oasiz/sdk] triggerHaptic bridge is unavailable. This is expected in local development."
+    );
+  }
+}
+
 // src/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -2771,7 +2988,7 @@ function warnMissingBridge7(methodName) {
     );
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber(value) {
@@ -2940,11 +3157,11 @@ function callBridgeFunction(bridge, name) {
   }
 }
 function readInsetObjectValue(value, side, group) {
-  if (!isRecord2(value)) {
+  if (!isRecord3(value)) {
     return void 0;
   }
   if (group) {
-    return isRecord2(value[group]) ? value[group][side] : void 0;
+    return isRecord3(value[group]) ? value[group][side] : void 0;
   }
   return value[side];
 }
@@ -3081,7 +3298,7 @@ function getBridgeWindow10() {
   }
   return window;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null;
 }
 function toFiniteNumber2(value) {
@@ -3147,7 +3364,7 @@ function normalizeMetric(value) {
     }
     return void 0;
   }
-  if (!isRecord3(value)) {
+  if (!isRecord4(value)) {
     return void 0;
   }
   const fpsCandidate = firstDefined2(
@@ -3397,6 +3614,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3458,6 +3677,8 @@ export {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   getViewportInsets,
   leaveGame,
   loadGameState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oasiz/sdk",
-  "version": "1.8.4",
+  "version": "1.8.6",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",