@oasiz/sdk 1.8.4 → 1.8.5

package/README.md

@@ -167,6 +167,38 @@ 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 returns a bundled sample Jibble atlas instead, so browser games can
+test sprite loading, atlas slicing, and animation lookup before publishing.
+
+The sample atlas includes every catalog ID above, and its `imageUrl` is an
+inline `data:image/svg+xml` URL. It does not make a network request and it is
+only used when the app bridge is missing.
+
+```ts
+const character = await oasiz.getPlayerCharacter();
+
+// In Oasiz app: the real signed-in player's character.
+// On localhost without the app bridge: "SDK 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 });
+
+// Or fetch the sample directly without checking the bridge.
+const directSample = oasiz.getSamplePlayerCharacter();
+```
+
 #### 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,223 @@ 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
+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.")
+    );
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    return useLocalFallback ? getSamplePlayerCharacter() : 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/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -3456,6 +3616,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3518,6 +3680,8 @@ var oasiz = {
   getPlayerName,
   getRoomCode,
   getSafeAreaTop,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   getViewportInsets,
   leaveGame,
   loadGameState,

package/dist/index.d.cts

@@ -220,13 +220,22 @@ 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";
+}
 /**
  * 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 +254,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 +390,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 +425,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 +455,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,22 @@ 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";
+}
 /**
  * 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 +254,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 +390,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 +425,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 +455,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,223 @@ 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
+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.")
+    );
+  }
+}
+async function getPlayerCharacter(options = {}) {
+  const bridge = getBridgeWindow2();
+  if (typeof bridge?.__oasizGetPlayerCharacter !== "function") {
+    const useLocalFallback = shouldUseLocalFallback(
+      bridge,
+      options.localFallback ?? "auto"
+    );
+    warnMissingBridge2("getPlayerCharacter", useLocalFallback);
+    return useLocalFallback ? getSamplePlayerCharacter() : 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/log-overlay.ts
 var CONSOLE_METHODS = [
   "debug",
@@ -3397,6 +3555,8 @@ var oasiz = {
   addScore,
   setScore,
   getPlayerCharacter,
+  getSamplePlayerCharacter,
+  getSampleTextureAtlas,
   share,
   triggerHaptic,
   enableLogOverlay,
@@ -3458,6 +3618,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.5",
   "description": "Typed SDK for Oasiz game platform bridge APIs.",
   "type": "module",
   "main": "./dist/index.cjs",