react-native-model-viewer-webview 0.1.0

package/AGENTS.md

@@ -0,0 +1,53 @@
+# React Native Model Viewer WebView Agent Notes
+
+This package provides `ModelViewerWebView`, a WebView-backed wrapper around
+Google's `<model-viewer>` web component for simple GLB/glTF previews in React
+Native and Expo apps.
+
+## Scope
+
+- Use this package for simple product, marketplace, demo, and vehicle model
+  previews where WebView rendering is acceptable.
+- Do not position it as a native 3D engine.
+- Recommend Filament, React Three Fiber Native, Three.js, or Expo GLView when
+  the user needs native GPU rendering, custom shaders, physics, AR, or complex
+  multi-object scenes.
+
+## Read First
+
+- `README.md` for consumer installation and usage.
+- `docs/HOW_IT_WORKS.md` for architecture and bridge behavior.
+- `docs/COMPATIBILITY.md` for supported and unverified React Native ranges.
+- `docs/AGENT_USAGE.md` for agent-facing skill/discovery files.
+- `docs-site/index.html` for the public GitHub Pages docs.
+- `agent-skills/react-native-model-viewer-webview/SKILL.md` when working as a
+  skills-compatible AI agent.
+
+## Development
+
+- Keep `src` and `dist` in sync. Package tests run against `dist` because npm
+  consumers load `dist`.
+- Add or update tests for behavior changes.
+- Keep docs honest about WebView tradeoffs and unsupported native 3D use cases.
+- Keep `docs-site` aligned with README examples and package limitations.
+- Do not widen peer dependency or React Native support claims without updating
+  `docs/COMPATIBILITY.md` and verifying the relevant app matrix.
+
+## Checks
+
+From this package directory:
+
+```bash
+npm test
+npm run typecheck
+npm run pack:dry-run
+```
+
+## Publishing
+
+- The npm package must include `AGENTS.md`, `llms.txt`, `docs`, and
+  `agent-skills`.
+- GitHub Pages deploys from `docs-site` through
+  `.github/workflows/pages.yml`.
+- Run `npm run pack:dry-run` and inspect the file list before release.
+- Release tags use `v<version>`.

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this package should be documented here.
+
+This project uses semantic versioning. Versions below `1.0.0` may still change
+minor APIs when the release notes call it out clearly.
+
+## 0.1.0 - 2026-05-31
+
+Initial public release of `react-native-model-viewer-webview`.
+
+### Added
+
+- Add `ModelViewerWebView`, a `react-native-webview` backed component for
+  rendering simple GLB and glTF previews through Google's `<model-viewer>` web
+  component.
+- Add `modelSource` support for remote URLs, `data:` URIs, `file:` URIs, React
+  Native static asset module numbers from `require(...)`, and Expo-style
+  `{ localUri, uri }` asset objects.
+- Keep `modelUri` as a string-only compatibility input for callers that already
+  have a resolved model URL.
+- Add `htmlOptions` for common `<model-viewer>` controls, including
+  `cameraControls`, `autoRotate`, camera orbit bounds, exposure, shadow
+  intensity, background color, poster color, and additional attributes.
+- Add status callbacks for model lifecycle handling:
+  `onStatus`, `onModelLoaded`, and `onModelError`.
+- Add offline script loading hooks through `modelViewerScriptUrl` and
+  `modelViewerScript`.
+- Export utility APIs for advanced consumers and tests:
+  `buildModelViewerHtml`, `parseModelViewerMessage`, and
+  `resolveModelSourceUri`.
+
+### Documentation
+
+- Add README guidance for Expo and bare React Native installation, local GLB
+  Metro setup, offline script loading, and when to choose native 3D stacks
+  instead.
+- Add `docs/HOW_IT_WORKS.md`, `docs/COMPATIBILITY.md`,
+  `docs/AGENT_USAGE.md`, and `docs/RELEASE.md`.
+- Add `CONTRIBUTING.md`, `SECURITY.md`, `AGENTS.md`, `llms.txt`, and a portable
+  Agent Skill for AI-assisted package integration.
+- Add a static GitHub Pages docs site with install instructions, examples,
+  direct answers for search/answer engines, use-case ideas, limitations, and
+  package-fit guidance.
+
+### Maintenance
+
+- Add Node test coverage for model source resolution, generated model-viewer
+  HTML, WebView status parsing, package exports, agent assets, docs site
+  metadata, and GitHub Pages workflow configuration.
+- Add TypeScript source checking and `npm pack --dry-run` verification through
+  `npm run check`.
+- Add GitHub Actions workflows for package CI, npm publishing, and GitHub Pages
+  deployment.
+
+### Known Limitations
+
+- `react-native-webview` is a peer dependency and must be installed by the
+  consuming app.
+- This package renders through WebView; it is not a native 3D renderer and is
+  not intended for shaders, physics, AR, complex scenes, or game-like
+  interaction.
+- React Native versions below `0.72` are unsupported.
+- Local `.glb` and `.gltf` imports still depend on the consuming app's Metro
+  asset configuration.
+- I am yet to test this on iOS. I will mark iOS as verified after I run a
+  WKWebView smoke test on an iOS device or simulator.

package/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing
+
+Thanks for helping improve `react-native-model-viewer-webview`.
+
+This package has a deliberately small scope: show GLB/glTF assets in React
+Native through WebView-backed `<model-viewer>` ergonomics. It should stay small,
+honest, and easy to reason about.
+
+## Ground Rules
+
+- Do not position this package as a replacement for Filament, React Three Fiber,
+  Three.js, or Expo GLView.
+- Keep the public API boring and explicit.
+- Prefer compatibility and clear failure modes over clever abstractions.
+- Add tests for utility behavior before changing implementation.
+- Keep `src` and `dist` in sync.
+- Document platform limitations instead of hiding them.
+
+## Local Checks
+
+From the package directory:
+
+```bash
+npm install
+npm run check
+```
+
+The package tests run against `dist`, because `dist` is what npm consumers load.
+If you change `src`, update `dist` before running tests.
+
+From the app directory:
+
+```bash
+cd ../../mobile
+npm install
+npx tsc --noEmit
+npm run lint
+```
+
+The mobile checks verify the local `file:` dependency and Metro/TypeScript
+integration used by this repository's Expo app.
+
+## Test Coverage Expectations
+
+Required for changes to:
+
+- HTML generation: escaping, attributes, script loading, and safe defaults.
+- Model source resolution: string URLs, data/file URLs, `localUri`, `uri`, and
+  React Native asset module numbers.
+- Status parsing: load events, error events, malformed payloads, and raw WebView
+  messages.
+- Public exports: avoid requiring React Native peers when a consumer imports only
+  utility functions.
+
+Component rendering tests are intentionally not faked with shallow mocks right
+now. WebView rendering confidence should come from real device smoke tests.
+
+## Pull Request Checklist
+
+- [ ] README updated when public behavior changes.
+- [ ] `docs/COMPATIBILITY.md` updated when peer ranges or platform claims change.
+- [ ] `CHANGELOG.md` updated under `Unreleased`.
+- [ ] `npm test` passes in the package.
+- [ ] `npm run typecheck` passes in the package after installing package deps.
+- [ ] `npm run pack:dry-run` shows only intended files.
+- [ ] Mobile integration checks pass from `mobile`.
+- [ ] Android device smoke test completed for rendering changes.
+- [ ] iOS device smoke test completed before claiming iOS support.
+
+## Release Contributions
+
+Release PRs should include:
+
+- version bump in `package.json`
+- `CHANGELOG.md` entry moved from `Unreleased` to the release version
+- fresh package dry-run output reviewed
+- Git tag created only after CI is green
+
+See [`docs/RELEASE.md`](./docs/RELEASE.md) for the full release procedure.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 react-native-model-viewer-webview contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# react-native-model-viewer-webview
+
+A tiny React Native and Expo wrapper around Google's `<model-viewer>` web
+component, rendered inside `react-native-webview`.
+
+It is for simple GLB/glTF previews, not for building a native 3D engine.
+
+## Why This Exists
+
+Use this package when your product requirement sounds like:
+
+> "Show this `.glb` in a React Native screen with orbit controls, auto-rotate,
+> lighting, and load/error callbacks."
+
+For that job, setting up Filament, Three.js, React Three Fiber, render loops,
+lights, cameras, loaders, and Metro asset details can be more machinery than the
+screen deserves. This package gives you the WebView version of the web
+`<model-viewer>` ergonomics.
+
+## When To Use It
+
+- Product cards or vehicle previews.
+- Marketplace listings with one inspectable 3D asset.
+- Expo demos and prototypes where WebView rendering is acceptable.
+- Apps that already use `<model-viewer>` on the web and want similar mobile
+  behavior.
+- Teams that want a small dependency and do not need full scene control.
+
+## When Not To Use It
+
+Use a native 3D stack instead when you need:
+
+- native GPU rendering as the core experience
+- custom materials, shaders, lights, or post-processing
+- physics, collision, skeletal animation control, or multi-object scenes
+- precise frame timing or heavy interaction
+- AR or game-like rendering
+
+Good alternatives:
+
+- [`react-native-filament`](https://margelo.github.io/react-native-filament/)
+  for a native mobile rendering engine.
+- [`@react-three/fiber/native`](https://r3f.docs.pmnd.rs/getting-started/installation#react-native)
+  for the Three.js ecosystem on React Native.
+- Expo [`GLView`](https://docs.expo.dev/versions/latest/sdk/gl-view/) when you
+  want lower-level WebGL control.
+
+## Install
+
+Expo:
+
+```bash
+npx expo install react-native-model-viewer-webview react-native-webview
+```
+
+Bare React Native:
+
+```bash
+npm install react-native-model-viewer-webview react-native-webview
+```
+
+If your app already has a compatible `react-native-webview`, install only
+`react-native-model-viewer-webview`. Bare React Native apps should follow
+`react-native-webview`'s native setup instructions.
+
+## Quick Start
+
+```tsx
+import { ModelViewerWebView } from "react-native-model-viewer-webview";
+
+export function CarPreview() {
+  return (
+    <ModelViewerWebView
+      modelSource="https://example.com/car.glb"
+      style={{ height: 320 }}
+      htmlOptions={{
+        autoRotate: true,
+        cameraControls: true,
+        cameraOrbit: "35deg 66deg 6.2m",
+        disablePan: true,
+        exposure: 1.05,
+        shadowIntensity: 0.35,
+      }}
+      onModelLoaded={(status) => {
+        console.log(status.message);
+      }}
+      onModelError={(status) => {
+        console.warn(status.message);
+      }}
+    />
+  );
+}
+```
+
+## Model Sources
+
+`modelSource` accepts:
+
+- a remote URL
+- a `data:` URI
+- a `file:` URI
+- a React Native static asset module number from `require(...)`
+- an object with `localUri` and/or `uri`, such as an Expo asset
+
+```tsx
+<ModelViewerWebView
+  modelSource={require("./assets/car.glb")}
+  style={{ height: 320 }}
+/>
+```
+
+```tsx
+import { Asset } from "expo-asset";
+import { ModelViewerWebView } from "react-native-model-viewer-webview";
+
+const carModel = Asset.fromModule(require("./assets/car.glb"));
+await carModel.downloadAsync();
+
+<ModelViewerWebView modelSource={carModel} style={{ height: 320 }} />;
+```
+
+`localUri` is preferred over `uri` when both exist. `modelUri` is still accepted
+as a string-only compatibility prop.
+
+## Metro Setup For Local GLB Files
+
+If your app imports `.glb` files, add `glb` to Metro's asset extensions.
+
+Expo example:
+
+```js
+const { getDefaultConfig } = require("expo/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.assetExts = [
+  ...config.resolver.assetExts,
+  "glb",
+  "gltf",
+];
+
+module.exports = config;
+```
+
+## Troubleshooting Local Package Development
+
+If you test this package through `file:../path`, `npm link`, or a monorepo
+symlink, make sure Metro resolves peer dependencies from the app, not from this
+package's local `node_modules`.
+
+Duplicate React copies can cause this error:
+
+```text
+Invalid hook call. Hooks can only be called inside of the body of a function component.
+```
+
+In that setup, alias `react`, `react-native`, and `react-native-webview` to the
+app's `node_modules`, and exclude any package-local dev copies of those peers
+from Metro's file map.
+
+## Offline Script Loading
+
+By default, the generated WebView HTML loads `<model-viewer>` from Google's CDN.
+That keeps the package tiny, but it means the viewer needs network access the
+first time the WebView loads.
+
+For offline apps, pass your own script URL:
+
+```tsx
+<ModelViewerWebView
+  modelSource={require("./assets/car.glb")}
+  htmlOptions={{
+    modelViewerScriptUrl: "file:///path/to/model-viewer.min.js",
+  }}
+/>
+```
+
+Or pass an inline module script if your build already bundles the source:
+
+```tsx
+<ModelViewerWebView
+  modelSource="https://example.com/car.glb"
+  htmlOptions={{
+    modelViewerScript: bundledModelViewerSource,
+  }}
+/>
+```
+
+## Props
+
+`ModelViewerWebView` accepts all `react-native-webview` props except `source` and
+`onMessage`, which are managed by the package.
+
+Important props:
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `modelSource` | `string \| number \| { localUri?: string; uri?: string }` | Preferred model input. |
+| `modelUri` | `string` | String-only compatibility input. |
+| `htmlOptions` | `ModelViewerHtmlOptions` | Controls `<model-viewer>` attributes and script loading. |
+| `onStatus` | `(status, event) => void` | Receives every status message from the WebView. |
+| `onModelLoaded` | `(status, event) => void` | Fires when `<model-viewer>` emits `load`. |
+| `onModelError` | `(status, event) => void` | Fires when page or model loading fails. |
+| `webViewBaseUrl` | `string` | Base URL used for the generated HTML. Defaults to `https://localhost/`. |
+
+Useful `htmlOptions`:
+
+| Option | Description |
+| --- | --- |
+| `autoRotate` | Adds `auto-rotate`. |
+| `cameraControls` | Adds `camera-controls`; defaults to `true`. |
+| `cameraOrbit` | Sets the initial orbit. |
+| `minCameraOrbit` / `maxCameraOrbit` | Bounds zoom/orbit. |
+| `disablePan` | Adds `disable-pan`. |
+| `exposure` / `shadowIntensity` | Basic visual tuning. |
+| `backgroundColor` / `posterColor` | Controls the WebView and poster background. |
+| `additionalAttributes` | Adds extra `<model-viewer>` attributes. |
+| `modelViewerScriptUrl` | Loads a custom `<model-viewer>` script URL. |
+| `modelViewerScript` | Inlines a custom module script. |
+
+## Example
+
+See [`example/App.tsx`](./example/App.tsx) for a minimal Expo screen.
+
+## More Documentation
+
+- [Public docs site](https://adityabhattad2021.github.io/react-native-model-viewer-webview/)
+- [How it works](./docs/HOW_IT_WORKS.md)
+- [Compatibility and support policy](./docs/COMPATIBILITY.md)
+- [AI agent usage](./docs/AGENT_USAGE.md)
+- [Release and maintenance guide](./docs/RELEASE.md)
+- [Contributing](./CONTRIBUTING.md)
+- [Security policy](./SECURITY.md)
+- [Changelog](./CHANGELOG.md)
+
+## AI Agent Support
+
+The package includes agent-facing docs so coding agents can integrate it without
+guessing:
+
+- [`AGENTS.md`](./AGENTS.md) for package-level agent instructions
+- [`llms.txt`](./llms.txt) as a compact docs index
+- [`agent-skills/react-native-model-viewer-webview/SKILL.md`](./agent-skills/react-native-model-viewer-webview/SKILL.md)
+  for skills-compatible agents
+
+Claude Code can use the skill after copying it to
+`~/.claude/skills/react-native-model-viewer-webview/SKILL.md` or a project-local
+`.claude/skills/react-native-model-viewer-webview/SKILL.md`.
+Installing from npm does not automatically install a skill into an agent client.
+See [AI agent usage](./docs/AGENT_USAGE.md) for copy/symlink instructions.
+
+## Development
+
+```bash
+npm test
+npm run typecheck
+npm run pack:dry-run
+```
+
+The test suite runs against `dist` because that is the code npm consumers load.
+When changing `src`, keep `dist` in sync before running the package tests.
+
+## Tradeoffs
+
+This package renders through WebView, so it inherits WebView tradeoffs:
+
+- startup cost is higher than a plain native view
+- WebView memory use can matter in long lists
+- native gestures and WebView gestures may need tuning in complex screens
+- rendering behavior follows the platform WebView
+
+The upside is simplicity. For many product preview surfaces, that is the whole
+point.
+
+## Pre-Publish Checklist
+
+Before publishing a release:
+
+- test a remote `.glb` on Android
+- test a bundled `.glb` on Android
+- test at least one iOS physical device if iOS support is claimed
+- test a no-network/offline script setup if documenting offline support
+- run `npm pack --dry-run`
+- keep the README positioning honest: this is not a Filament/R3F replacement
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are applied to the latest published minor version. Before `1.0.0`,
+only the latest published version is supported.
+
+## Reporting A Vulnerability
+
+Do not open public issues for vulnerabilities.
+
+Report privately through the repository owner's preferred security channel. If
+GitHub private vulnerability reporting is enabled, use that. Otherwise, contact
+the maintainer directly and include:
+
+- package version
+- affected platform and React Native version
+- reproduction steps
+- impact
+- whether the issue requires a malicious model file, malicious model URL, or
+  malicious app input
+
+## Security Considerations
+
+This package generates HTML and runs it inside `react-native-webview`.
+
+- Treat untrusted model URLs as remote content.
+- Prefer trusted domains or bundled assets for production apps.
+- Avoid passing untrusted strings through `additionalAttributes`.
+- Use offline script loading for apps that cannot rely on CDN availability.
+- Keep `react-native-webview` updated in consuming apps.

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

@@ -0,0 +1,134 @@
+---
+name: react-native-model-viewer-webview
+description: Use when adding, configuring, debugging, or reviewing react-native-model-viewer-webview in a React Native or Expo app, especially for simple GLB/glTF model previews rendered with WebView instead of Filament, React Three Fiber, Three.js, or Expo GLView.
+---
+
+# React Native Model Viewer WebView
+
+Use this skill to help users integrate `react-native-model-viewer-webview`.
+
+## First Decision
+
+Confirm the package is the right tool:
+
+- Use it for simple GLB/glTF product previews, vehicle previews, marketplace cards, and demos where WebView rendering is acceptable.
+- Recommend `react-native-filament`, `@react-three/fiber/native`, Three.js, or Expo GLView when the user needs native GPU rendering, custom shaders/materials, physics, AR, many scene objects, or game-like interaction.
+
+Do not describe this package as a native 3D engine.
+
+## Install
+
+Expo:
+
+```bash
+npx expo install react-native-model-viewer-webview react-native-webview
+```
+
+Bare React Native:
+
+```bash
+npm install react-native-model-viewer-webview react-native-webview
+```
+
+If the app already has a compatible `react-native-webview`, install only
+`react-native-model-viewer-webview`. For bare React Native apps, follow
+`react-native-webview` native setup.
+
+## Basic Usage
+
+```tsx
+import { ModelViewerWebView } from "react-native-model-viewer-webview";
+
+export function ProductModel() {
+  return (
+    <ModelViewerWebView
+      modelSource="https://example.com/model.glb"
+      style={{ height: 320 }}
+      htmlOptions={{
+        autoRotate: true,
+        cameraControls: true,
+        exposure: 1.05,
+        shadowIntensity: 0.35,
+      }}
+    />
+  );
+}
+```
+
+## Local GLB Files
+
+If the user imports local `.glb` or `.gltf` files, tell them to add those
+extensions to Metro asset extensions.
+
+Expo `metro.config.js`:
+
+```js
+const { getDefaultConfig } = require("expo/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.assetExts = [
+  ...config.resolver.assetExts,
+  "glb",
+  "gltf",
+];
+
+module.exports = config;
+```
+
+Then:
+
+```tsx
+<ModelViewerWebView modelSource={require("./assets/model.glb")} />
+```
+
+## Expo Asset Objects
+
+```tsx
+import { Asset } from "expo-asset";
+import { ModelViewerWebView } from "react-native-model-viewer-webview";
+
+const model = Asset.fromModule(require("./assets/model.glb"));
+await model.downloadAsync();
+
+<ModelViewerWebView modelSource={model} />;
+```
+
+## Offline Apps
+
+By default, `<model-viewer>` loads from Google's CDN. For offline apps, use:
+
+```tsx
+<ModelViewerWebView
+  modelSource={require("./assets/model.glb")}
+  htmlOptions={{
+    modelViewerScriptUrl: "file:///path/to/model-viewer.min.js",
+  }}
+/>
+```
+
+or:
+
+```tsx
+<ModelViewerWebView
+  modelSource="https://example.com/model.glb"
+  htmlOptions={{
+    modelViewerScript: bundledModelViewerSource,
+  }}
+/>
+```
+
+## Debugging Checklist
+
+When the model does not render:
+
+1. Verify the app has `react-native-webview` installed.
+2. For local files, verify Metro includes `glb` and `gltf`.
+3. Check whether `onModelError` receives a page or model error.
+4. Try a known remote GLB to separate asset-loading problems from WebView problems.
+5. Test on a real Android or iOS device before claiming platform support.
+6. If native rendering quality or performance is the issue, recommend Filament or React Three Fiber Native instead.
+
+## References
+
+Read `references/api.md` when you need the package API surface.

package/agent-skills/react-native-model-viewer-webview/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "React Native Model Viewer WebView"
+  short_description: "Add simple GLB previews to React Native"
+  default_prompt: "Use $react-native-model-viewer-webview to add a simple GLB preview to my Expo screen."