react-native-model-viewer-webview 0.1.0

package/agent-skills/react-native-model-viewer-webview/references/api.md

@@ -0,0 +1,86 @@
+# API Reference For Agents
+
+## Component
+
+```tsx
+<ModelViewerWebView
+  modelSource={source}
+  modelUri="https://example.com/model.glb"
+  htmlOptions={options}
+  onStatus={(status, event) => {}}
+  onModelLoaded={(status, event) => {}}
+  onModelError={(status, event) => {}}
+  webViewBaseUrl="https://localhost/"
+/>
+```
+
+`ModelViewerWebView` accepts all `react-native-webview` props except `source`
+and `onMessage`.
+
+Prefer `modelSource` over `modelUri`.
+
+## ModelSource
+
+```ts
+type ModelSource =
+  | string
+  | number
+  | {
+      localUri?: null | string;
+      uri?: null | string;
+    };
+```
+
+Use:
+
+- remote URL: `"https://example.com/model.glb"`
+- data URI: `"data:model/gltf-binary;base64,..."`
+- file URI: `"file:///.../model.glb"`
+- static asset: `require("./assets/model.glb")`
+- Expo asset object: `Asset.fromModule(require("./assets/model.glb"))`
+
+## HTML Options
+
+```ts
+type ModelViewerHtmlOptions = {
+  additionalAttributes?: Record<string, boolean | number | string | null | undefined>;
+  autoRotate?: boolean;
+  autoRotateDelay?: number | string;
+  backgroundColor?: string;
+  cameraControls?: boolean;
+  cameraOrbit?: string;
+  disablePan?: boolean;
+  exposure?: number | string;
+  interactionPrompt?: "auto" | "none";
+  maxCameraOrbit?: string;
+  minCameraOrbit?: string;
+  modelUri: string;
+  modelViewerScript?: string;
+  modelViewerScriptUrl?: string;
+  posterColor?: string;
+  rotationPerSecond?: string;
+  shadowIntensity?: number | string;
+};
+```
+
+Consumers pass `htmlOptions` without `modelUri`; the component injects it.
+
+## Utility Functions
+
+```ts
+buildModelViewerHtml(options)
+parseModelViewerMessage(data)
+isModelViewerErrorStatus(status)
+resolveModelSourceUri(modelSource)
+```
+
+Use utilities for tests or custom wrappers. Most apps should use the component.
+
+## Event Types
+
+- `dom-ready`
+- `model-loaded`
+- `model-error`
+- `page-error`
+
+Statuses ending in `error` trigger `onModelError`.

package/dist/ModelViewerWebView.d.ts

@@ -0,0 +1,19 @@
+import type { ReactElement } from "react";
+import type { WebViewMessageEvent, WebViewProps } from "react-native-webview";
+
+import type { ModelViewerHtmlOptions, ModelViewerStatus } from "./model-viewer-html";
+import type { ModelSource } from "./model-source";
+
+export type ModelViewerWebViewProps = Omit<WebViewProps, "onMessage" | "source"> & {
+  htmlOptions?: Omit<ModelViewerHtmlOptions, "modelUri">;
+  modelSource?: ModelSource;
+  modelUri?: string;
+  onModelError?: (status: ModelViewerStatus, event: WebViewMessageEvent) => void;
+  onModelLoaded?: (status: ModelViewerStatus, event: WebViewMessageEvent) => void;
+  onStatus?: (status: ModelViewerStatus, event: WebViewMessageEvent) => void;
+  webViewBaseUrl?: string;
+};
+
+export declare function ModelViewerWebView(
+  props: ModelViewerWebViewProps,
+): ReactElement;

package/dist/ModelViewerWebView.js

@@ -0,0 +1,90 @@
+const React = require("react");
+const { WebView } = require("react-native-webview");
+
+const {
+  buildModelViewerHtml,
+  isModelViewerErrorStatus,
+  MODEL_VIEWER_LOADED_EVENT,
+  parseModelViewerMessage,
+} = require("./model-viewer-html");
+const { resolveModelSourceUri } = require("./model-source");
+
+function ModelViewerWebView({
+  allowFileAccess = true,
+  allowFileAccessFromFileURLs = true,
+  allowUniversalAccessFromFileURLs = true,
+  androidLayerType = "hardware",
+  bounces = false,
+  domStorageEnabled = true,
+  htmlOptions,
+  javaScriptEnabled = true,
+  mixedContentMode = "always",
+  modelSource,
+  modelUri,
+  onModelError,
+  onModelLoaded,
+  onStatus,
+  originWhitelist = ["*"],
+  scrollEnabled = false,
+  setSupportMultipleWindows = false,
+  webViewBaseUrl = "https://localhost/",
+  ...webViewProps
+}) {
+  const resolvedModelUri = React.useMemo(() => {
+    if (modelSource !== undefined) {
+      return resolveModelSourceUri(modelSource);
+    }
+
+    if (modelUri !== undefined) {
+      return modelUri;
+    }
+
+    throw new Error("ModelViewerWebView requires modelSource or modelUri.");
+  }, [modelSource, modelUri]);
+
+  const html = React.useMemo(
+    () =>
+      buildModelViewerHtml({
+        ...htmlOptions,
+        modelUri: resolvedModelUri,
+      }),
+    [htmlOptions, resolvedModelUri],
+  );
+
+  function handleMessage(event) {
+    const status = parseModelViewerMessage(event.nativeEvent.data);
+
+    onStatus?.(status, event);
+
+    if (status.type === MODEL_VIEWER_LOADED_EVENT) {
+      onModelLoaded?.(status, event);
+      return;
+    }
+
+    if (isModelViewerErrorStatus(status)) {
+      onModelError?.(status, event);
+    }
+  }
+
+  return React.createElement(WebView, {
+    allowFileAccess,
+    allowFileAccessFromFileURLs,
+    allowUniversalAccessFromFileURLs,
+    androidLayerType,
+    bounces,
+    domStorageEnabled,
+    javaScriptEnabled,
+    mixedContentMode,
+    onMessage: handleMessage,
+    originWhitelist,
+    scrollEnabled,
+    setSupportMultipleWindows,
+    source: {
+      baseUrl: webViewBaseUrl,
+      html,
+    },
+    ...webViewProps,
+  });
+}
+
+exports.ModelViewerWebView = ModelViewerWebView;

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export {
+  ModelViewerWebView,
+  type ModelViewerWebViewProps,
+} from "./ModelViewerWebView";
+export {
+  buildModelViewerHtml,
+  DEFAULT_MODEL_VIEWER_SCRIPT_URL,
+  isModelViewerErrorStatus,
+  MODEL_VIEWER_DOM_READY_EVENT,
+  MODEL_VIEWER_LOADED_EVENT,
+  MODEL_VIEWER_MODEL_ERROR_EVENT,
+  MODEL_VIEWER_PAGE_ERROR_EVENT,
+  parseModelViewerMessage,
+  type ModelViewerHtmlOptions,
+  type ModelViewerStatus,
+} from "./model-viewer-html";
+export {
+  resolveModelSourceUri,
+  type ModelSource,
+} from "./model-source";

package/dist/index.js

@@ -0,0 +1,17 @@
+const modelViewerHtml = require("./model-viewer-html");
+
+Object.assign(exports, modelViewerHtml);
+
+Object.defineProperty(exports, "ModelViewerWebView", {
+  enumerable: true,
+  get() {
+    return require("./ModelViewerWebView").ModelViewerWebView;
+  },
+});
+
+Object.defineProperty(exports, "resolveModelSourceUri", {
+  enumerable: true,
+  get() {
+    return require("./model-source").resolveModelSourceUri;
+  },
+});

package/dist/model-source.d.ts

@@ -0,0 +1,9 @@
+export type ModelSource =
+  | string
+  | number
+  | {
+      localUri?: null | string;
+      uri?: null | string;
+    };
+
+export declare function resolveModelSourceUri(modelSource: ModelSource): string;

package/dist/model-source.js

@@ -0,0 +1,31 @@
+function resolveModelSourceUri(modelSource) {
+  if (typeof modelSource === "string") {
+    return modelSource;
+  }
+
+  if (
+    typeof modelSource === "object" &&
+    modelSource.localUri &&
+    modelSource.localUri.length > 0
+  ) {
+    return modelSource.localUri;
+  }
+
+  if (
+    typeof modelSource === "object" &&
+    modelSource.uri &&
+    modelSource.uri.length > 0
+  ) {
+    return modelSource.uri;
+  }
+
+  const { Image } = require("react-native");
+  const resolved = Image.resolveAssetSource(modelSource);
+  if (resolved?.uri) {
+    return resolved.uri;
+  }
+
+  throw new Error("Unable to resolve model source URI.");
+}
+
+exports.resolveModelSourceUri = resolveModelSourceUri;

package/dist/model-viewer-html.d.ts

@@ -0,0 +1,35 @@
+export declare const DEFAULT_MODEL_VIEWER_SCRIPT_URL = "https://ajax.googleapis.com/ajax/libs/model-viewer/4.2.0/model-viewer.min.js";
+export declare const MODEL_VIEWER_DOM_READY_EVENT = "dom-ready";
+export declare const MODEL_VIEWER_LOADED_EVENT = "model-loaded";
+export declare const MODEL_VIEWER_MODEL_ERROR_EVENT = "model-error";
+export declare const MODEL_VIEWER_PAGE_ERROR_EVENT = "page-error";
+
+export type ModelViewerStatus = {
+  message?: string;
+  rawData?: string;
+  type: string;
+};
+
+export type ModelViewerHtmlOptions = {
+  additionalAttributes?: Record<string, boolean | number | string | null | undefined>;
+  autoRotate?: boolean;
+  autoRotateDelay?: number | string;
+  backgroundColor?: string;
+  cameraControls?: boolean;
+  cameraOrbit?: string;
+  disablePan?: boolean;
+  exposure?: number | string;
+  interactionPrompt?: "auto" | "none";
+  maxCameraOrbit?: string;
+  minCameraOrbit?: string;
+  modelUri: string;
+  modelViewerScript?: string;
+  modelViewerScriptUrl?: string;
+  posterColor?: string;
+  rotationPerSecond?: string;
+  shadowIntensity?: number | string;
+};
+
+export declare function buildModelViewerHtml(options: ModelViewerHtmlOptions): string;
+export declare function parseModelViewerMessage(data: string): ModelViewerStatus;
+export declare function isModelViewerErrorStatus(status: ModelViewerStatus): boolean;

package/dist/model-viewer-html.js

@@ -0,0 +1,187 @@
+const DEFAULT_MODEL_VIEWER_SCRIPT_URL =
+  "https://ajax.googleapis.com/ajax/libs/model-viewer/4.2.0/model-viewer.min.js";
+
+const MODEL_VIEWER_DOM_READY_EVENT = "dom-ready";
+const MODEL_VIEWER_LOADED_EVENT = "model-loaded";
+const MODEL_VIEWER_MODEL_ERROR_EVENT = "model-error";
+const MODEL_VIEWER_PAGE_ERROR_EVENT = "page-error";
+
+function buildModelViewerHtml(options) {
+  const backgroundColor = sanitizeCssColor(options.backgroundColor ?? "#ffffff");
+  const posterColor = sanitizeCssColor(options.posterColor ?? backgroundColor);
+  const modelViewerScriptTag = getModelViewerScriptTag(options);
+  const attributes = [
+    htmlAttribute("src", options.modelUri),
+    htmlAttribute("camera-controls", options.cameraControls ?? true),
+    htmlAttribute("auto-rotate", options.autoRotate ?? false),
+    htmlAttribute("auto-rotate-delay", options.autoRotateDelay),
+    htmlAttribute("rotation-per-second", options.rotationPerSecond),
+    htmlAttribute("interaction-prompt", options.interactionPrompt ?? "none"),
+    htmlAttribute("camera-orbit", options.cameraOrbit),
+    htmlAttribute("min-camera-orbit", options.minCameraOrbit),
+    htmlAttribute("max-camera-orbit", options.maxCameraOrbit),
+    htmlAttribute("shadow-intensity", options.shadowIntensity),
+    htmlAttribute("exposure", options.exposure),
+    htmlAttribute("disable-pan", options.disablePan ?? false),
+    ...Object.entries(options.additionalAttributes ?? {}).map(([name, value]) =>
+      htmlAttribute(name, value),
+    ),
+  ].join("");
+
+  return `<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"
+    />
+    ${modelViewerScriptTag}
+    <script>
+      function postStatus(type, message) {
+        window.ReactNativeWebView &&
+          window.ReactNativeWebView.postMessage(JSON.stringify({ type, message }));
+      }
+
+      window.addEventListener("error", function (event) {
+        postStatus("${MODEL_VIEWER_PAGE_ERROR_EVENT}", event.message || "Page error");
+      });
+
+      window.addEventListener("unhandledrejection", function (event) {
+        postStatus("${MODEL_VIEWER_PAGE_ERROR_EVENT}", String(event.reason || "Unhandled rejection"));
+      });
+
+      window.addEventListener("DOMContentLoaded", function () {
+        var viewer = document.querySelector("model-viewer");
+        postStatus("${MODEL_VIEWER_DOM_READY_EVENT}", "Model viewer DOM ready");
+
+        if (!viewer) {
+          postStatus("${MODEL_VIEWER_MODEL_ERROR_EVENT}", "model-viewer element was not created");
+          return;
+        }
+
+        viewer.addEventListener("load", function () {
+          postStatus("${MODEL_VIEWER_LOADED_EVENT}", "3D model loaded");
+        });
+
+        viewer.addEventListener("error", function (event) {
+          var detail = event.detail || {};
+          var sourceError = detail.sourceError || {};
+          postStatus(
+            "${MODEL_VIEWER_MODEL_ERROR_EVENT}",
+            sourceError.message || detail.message || "3D model failed to load"
+          );
+        });
+      });
+    </script>
+    <style>
+      html,
+      body {
+        background: ${backgroundColor};
+        height: 100%;
+        margin: 0;
+        overflow: hidden;
+        width: 100%;
+      }
+
+      model-viewer {
+        --poster-color: ${posterColor};
+        background: ${backgroundColor};
+        height: 100%;
+        width: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <model-viewer${attributes}></model-viewer>
+  </body>
+</html>`;
+}
+
+function parseModelViewerMessage(data) {
+  try {
+    const parsed = JSON.parse(data);
+
+    if (parsed && typeof parsed.type === "string") {
+      return {
+        message: typeof parsed.message === "string" ? parsed.message : undefined,
+        rawData: data,
+        type: parsed.type,
+      };
+    }
+  } catch {
+    return {
+      message: data,
+      rawData: data,
+      type: MODEL_VIEWER_PAGE_ERROR_EVENT,
+    };
+  }
+
+  return {
+    message: data,
+    rawData: data,
+    type: MODEL_VIEWER_PAGE_ERROR_EVENT,
+  };
+}
+
+function isModelViewerErrorStatus(status) {
+  return status.type.endsWith("error");
+}
+
+function getModelViewerScriptTag(options) {
+  if (options.modelViewerScript) {
+    return `<script type="module">${escapeScriptContent(options.modelViewerScript)}</script>`;
+  }
+
+  const scriptUrl = options.modelViewerScriptUrl ?? DEFAULT_MODEL_VIEWER_SCRIPT_URL;
+  return `<script type="module" src="${escapeHtmlAttribute(scriptUrl)}"></script>`;
+}
+
+function htmlAttribute(name, value) {
+  if (!isSafeAttributeName(name)) {
+    return "";
+  }
+
+  if (value === false || value === null || value === undefined) {
+    return "";
+  }
+
+  if (value === true) {
+    return ` ${name}`;
+  }
+
+  return ` ${name}="${escapeHtmlAttribute(String(value))}"`;
+}
+
+function isSafeAttributeName(name) {
+  return /^[a-zA-Z][\w:.-]*$/.test(name);
+}
+
+function escapeHtmlAttribute(value) {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/"/g, "&quot;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function escapeScriptContent(value) {
+  return value.replace(/<\/script/gi, "<\\/script");
+}
+
+function sanitizeCssColor(value) {
+  if (/^[#(),.%\w\s-]+$/.test(value)) {
+    return value;
+  }
+
+  return "#ffffff";
+}
+
+exports.DEFAULT_MODEL_VIEWER_SCRIPT_URL = DEFAULT_MODEL_VIEWER_SCRIPT_URL;
+exports.MODEL_VIEWER_DOM_READY_EVENT = MODEL_VIEWER_DOM_READY_EVENT;
+exports.MODEL_VIEWER_LOADED_EVENT = MODEL_VIEWER_LOADED_EVENT;
+exports.MODEL_VIEWER_MODEL_ERROR_EVENT = MODEL_VIEWER_MODEL_ERROR_EVENT;
+exports.MODEL_VIEWER_PAGE_ERROR_EVENT = MODEL_VIEWER_PAGE_ERROR_EVENT;
+exports.buildModelViewerHtml = buildModelViewerHtml;
+exports.isModelViewerErrorStatus = isModelViewerErrorStatus;
+exports.parseModelViewerMessage = parseModelViewerMessage;

package/docs/AGENT_USAGE.md

@@ -0,0 +1,124 @@
+# AI Agent Usage
+
+This package ships agent-facing context so AI coding agents can integrate it
+without guessing at the API shape or overselling the package.
+
+## What We Ship
+
+- `AGENTS.md`: package-level instructions for coding agents working inside this
+  repository or an unpacked npm tarball.
+- `llms.txt`: a compact documentation index agents can read before choosing
+  deeper files.
+- `agent-skills/react-native-model-viewer-webview/SKILL.md`: a portable Agent
+  Skill for tools that support filesystem skills.
+- `agent-skills/react-native-model-viewer-webview/references/api.md`: a smaller
+  API reference loaded only when the skill needs it.
+- `agent-skills/react-native-model-viewer-webview/agents/openai.yaml`:
+  UI-facing metadata for OpenAI/Codex-style skill lists.
+
+## Current Conventions
+
+Agent Skills use a directory containing `SKILL.md` with YAML frontmatter and
+Markdown instructions. The public Agent Skills specification defines `name` and
+`description` as required fields, plus optional resources such as `references`,
+`scripts`, and `assets`. Claude Code documents the same `SKILL.md` workflow and
+project/personal skill locations.
+
+`AGENTS.md` is the cross-agent repository instruction file. It is plain Markdown
+and is intended to hold build commands, test commands, code style, security
+notes, and package-specific constraints.
+
+`llms.txt` is an emerging Markdown index convention for LLM-readable docs. It is
+useful because it gives agents a curated map of the docs, but it is not a W3C or
+IETF standard and no package manager automatically wires it into agent clients.
+
+Useful references:
+
+- Agent Skills overview: https://agentskills.io/
+- Agent Skills specification: https://agentskills.io/specification
+- Claude Code skills docs: https://code.claude.com/docs/en/skills
+- AGENTS.md format: https://agents.md/
+- llms.txt reference: https://llmtxt.info/
+
+## Claude Code Support
+
+Installing the npm package does not automatically install a skill into a user's
+agent. That is intentional: agent clients keep skills in their own trusted
+locations, and users should review third-party skills before enabling them.
+
+Claude Code supports this skill because it is a directory containing
+`SKILL.md` with YAML frontmatter, Markdown instructions, and optional supporting
+files. We do not use `allowed-tools` in the skill frontmatter, because Claude
+Code supports it but the Claude Agent SDK handles tool access through SDK
+options instead.
+
+Personal Claude Code install:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R node_modules/react-native-model-viewer-webview/agent-skills/react-native-model-viewer-webview ~/.claude/skills/
+ls ~/.claude/skills/react-native-model-viewer-webview/SKILL.md
+```
+
+Project Claude Code install, for teams that want to commit the skill into an app
+repository:
+
+```bash
+mkdir -p .claude/skills
+cp -R node_modules/react-native-model-viewer-webview/agent-skills/react-native-model-viewer-webview .claude/skills/
+ls .claude/skills/react-native-model-viewer-webview/SKILL.md
+```
+
+After installing, ask Claude Code:
+
+```text
+What Skills are available?
+```
+
+or invoke it directly:
+
+```text
+/react-native-model-viewer-webview add a GLB preview to this Expo screen
+```
+
+If Claude does not list or use the skill, verify the filesystem path and run:
+
+```bash
+claude --debug
+```
+
+Claude Agent SDK users should make sure user or project settings are loaded and
+the skill is enabled. In Python SDK terms, that means `setting_sources` includes
+`"user"` or `"project"` and `skills="all"` or a list containing
+`"react-native-model-viewer-webview"`.
+
+## Other Agent Clients
+
+After installing the package, users can copy or symlink the skill folder into
+their agent's supported skills directory.
+
+Codex-style clients that support filesystem skills can use the same skill folder
+from their configured skills directory. If the client does not support skills,
+point the agent at `llms.txt`, `AGENTS.md`, and the package README instead.
+
+## What Agents Should Do
+
+When a user asks to add this package to a React Native or Expo app:
+
+1. Confirm the requirement is a simple GLB/glTF preview, not a native 3D engine.
+2. Install `react-native-model-viewer-webview` and `react-native-webview`.
+3. Use `modelSource` for URLs, static asset module numbers, file/data URIs, or
+   Expo asset-like objects.
+4. For local `.glb` or `.gltf` imports, add those extensions to Metro asset
+   extensions.
+5. Use `onModelLoaded`, `onModelError`, and `onStatus` for instrumentation.
+6. Recommend Filament, React Three Fiber Native, Three.js, or Expo GLView when
+   the user needs native rendering or full scene control.
+
+## Maintenance Checklist
+
+- Keep `SKILL.md` concise and put detailed API material in `references/api.md`.
+- Keep `agents/openai.yaml` in sync with `SKILL.md`.
+- Keep `llms.txt` links aligned with published docs.
+- Keep `AGENTS.md` aligned with package scripts and release policy.
+- Run `npm test` after changing agent assets; tests pin the expected files.