react-native-model-viewer-webview 0.1.0

package/docs/COMPATIBILITY.md

@@ -0,0 +1,112 @@
+# Compatibility And Support Policy
+
+This package is a WebView bridge. Compatibility depends on:
+
+- React
+- React Native
+- `react-native-webview`
+- the Android System WebView or iOS WKWebView
+- Google's `<model-viewer>` web component
+- how the consuming app bundles `.glb` and `.gltf` files
+
+## Supported Peer Ranges
+
+```json
+{
+  "react": ">=18",
+  "react-native": ">=0.72",
+  "react-native-webview": ">=13"
+}
+```
+
+These ranges describe the intended support window, not a claim that every patch
+release has been manually device-tested.
+
+## Tested In This Repository
+
+Current local integration target:
+
+- Expo SDK 54
+- React 19.1
+- React Native 0.81
+- `react-native-webview` 13.15
+- TypeScript 5.9
+
+Automated checks validate:
+
+- package utility behavior with Node's built-in test runner
+- package source typechecking when package dependencies are installed
+- package tarball contents with `npm pack --dry-run`
+- integration with this repository's Expo app through TypeScript and Expo lint
+
+## Not Guaranteed
+
+The package does not claim blanket support for all React Native versions.
+
+Explicit limitations:
+
+- React Native below `0.72` is unsupported.
+- WebView bugs in specific Android System WebView or iOS versions may affect
+  rendering.
+- Local `.glb` bundling depends on the consuming app's Metro config.
+- Device rendering is not fully proven by unit tests.
+- AR behavior is not a supported package guarantee.
+- Long lists of many WebViews may have memory/performance problems.
+
+## Compatibility Review Checklist
+
+Before expanding peer ranges or claiming support for a platform/version:
+
+- install the package in a clean Expo app
+- render a remote `.glb`
+- render a bundled `.glb`
+- verify `onModelLoaded`
+- verify a failed model URL triggers `onModelError`
+- test Android physical device or emulator
+- test iOS physical device or simulator if claiming iOS support
+- update this document with the tested versions
+
+## Recommended Consumer Setup
+
+For Expo apps:
+
+```bash
+npx expo install react-native-model-viewer-webview react-native-webview
+```
+
+For bare React Native apps:
+
+```bash
+npm install react-native-model-viewer-webview react-native-webview
+```
+
+For local `.glb` imports, add `glb` and `gltf` to Metro's asset extensions.
+See the package README for an example.
+
+## Local Symlink And `file:` Dependency Setup
+
+When developing this package from a local checkout, avoid letting Metro load
+peer dependencies from the package's own `node_modules`.
+
+This package keeps `react`, `react-native`, and `react-native-webview` as peer
+dependencies. A published npm install does not include this package's
+development `node_modules`, but a local symlink or `file:../package` install can
+expose them to Metro. If Metro bundles a package-local copy of React, the app
+can fail with an invalid hook call even when both copies have the same version.
+
+For local development, configure the consuming app's Metro setup to:
+
+- watch the local package folder
+- resolve `react`, `react-native`, and `react-native-webview` from the app's
+  `node_modules`
+- exclude package-local dev copies of those peer dependencies from Metro's file
+  map
+
+## Dependency Update Policy
+
+- Keep `react-native-webview` peer range broad unless a real incompatibility is
+  found.
+- Keep dev dependencies pinned to one known-good React Native stack.
+- Use CI and device smoke tests before raising support claims.
+- If `<model-viewer>` changes behavior, update README examples and tests before
+  changing the default CDN URL.

package/docs/HOW_IT_WORKS.md

@@ -0,0 +1,126 @@
+# How It Works
+
+`react-native-model-viewer-webview` is a small adapter around three pieces:
+
+1. React Native renders a `react-native-webview` instance.
+2. The package generates a complete HTML document containing Google's
+   `<model-viewer>` web component.
+3. The WebView sends structured status messages back to React Native through
+   `window.ReactNativeWebView.postMessage`.
+
+It does not implement a renderer. The renderer is the platform WebView running
+`<model-viewer>`.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  RN["React Native screen"] --> Component["ModelViewerWebView"]
+  Component --> Source["resolveModelSourceUri"]
+  Component --> HTML["buildModelViewerHtml"]
+  HTML --> WebView["react-native-webview"]
+  WebView --> ModelViewer["<model-viewer>"]
+  ModelViewer --> Events["load/error events"]
+  Events --> Bridge["postMessage JSON status"]
+  Bridge --> Component
+```
+
+## Why WebView
+
+Native 3D stacks are better when 3D is the product. This package exists for the
+opposite case: 3D is a preview inside a normal app screen.
+
+Using WebView gives us:
+
+- the same high-level `<model-viewer>` API used on the web
+- simple camera controls and auto-rotate
+- GLB/glTF support delegated to a maintained web component
+- a small React Native API surface
+- compatibility with Expo and bare React Native apps that already support
+  `react-native-webview`
+
+It also means:
+
+- startup cost is higher than a native view
+- WebView memory matters in long lists
+- WebView gesture behavior may need screen-level tuning
+- rendering quality and bugs depend on the platform WebView
+
+## Source Resolution
+
+`resolveModelSourceUri` accepts:
+
+- string URLs, including `https:`, `data:`, and `file:`
+- React Native static asset module numbers from `require(...)`
+- asset-like objects with `localUri` and/or `uri`
+
+For objects, `localUri` wins over `uri` because local files are preferred after
+an Expo asset has been downloaded.
+
+For module numbers, the package calls `Image.resolveAssetSource`. React Native
+does not have a dedicated generic asset resolver with equivalent availability,
+so `Image.resolveAssetSource` is used as the practical stable option.
+
+## HTML Generation
+
+`buildModelViewerHtml` creates a full HTML document with:
+
+- viewport metadata
+- a `<model-viewer>` script tag
+- WebView status bridge helpers
+- a full-size `<model-viewer>` element
+- generated model-viewer attributes
+
+Attribute values are HTML-escaped. Attribute names must match a conservative
+safe-name pattern before they are emitted. Basic CSS color values are sanitized
+to avoid injecting arbitrary CSS into generated HTML.
+
+## Script Loading
+
+By default, the HTML loads:
+
+```text
+https://ajax.googleapis.com/ajax/libs/model-viewer/4.2.0/model-viewer.min.js
+```
+
+Apps that need offline behavior can provide either:
+
+- `modelViewerScriptUrl`, such as a `file:` URL to a bundled script
+- `modelViewerScript`, an inline module script string
+
+Inline script content escapes closing `</script>` sequences to avoid breaking
+the generated document.
+
+## Event Flow
+
+The generated HTML posts JSON messages:
+
+```json
+{ "type": "dom-ready", "message": "Model viewer DOM ready" }
+```
+
+Important event types:
+
+- `dom-ready`
+- `model-loaded`
+- `model-error`
+- `page-error`
+
+`ModelViewerWebView` parses these messages and exposes:
+
+- `onStatus` for every status
+- `onModelLoaded` for `model-loaded`
+- `onModelError` for statuses ending in `error`
+
+Raw or malformed WebView messages are converted into `page-error` statuses.
+
+## What This Package Does Not Do
+
+- It does not implement native rendering.
+- It does not expose a scene graph.
+- It does not manage physics, shaders, or multiple model scenes.
+- It does not guarantee AR support.
+- It does not guarantee identical rendering across Android and iOS WebViews.
+
+Those are native renderer concerns. Use Filament, React Three Fiber Native, or
+Expo GLView for those workloads.

package/docs/RELEASE.md

@@ -0,0 +1,169 @@
+# Release And Maintenance Guide
+
+This guide describes how to publish and maintain
+`react-native-model-viewer-webview`.
+
+The preferred release path is GitHub Actions plus npm Trusted Publishing. npm
+documents Trusted Publishing as an OIDC-based flow that avoids long-lived npm
+tokens and automatically generates provenance for supported public packages.
+
+## Release Workflow Summary
+
+1. Land changes through a PR.
+2. Run package checks and manual device smoke tests.
+3. Update `CHANGELOG.md`.
+4. Bump `package.json` version.
+5. Create a GitHub release or release tag.
+6. Let GitHub Actions publish to npm through Trusted Publishing.
+7. Verify the npm package page and install from a clean app.
+
+## One-Time npm Setup
+
+On npmjs.com, configure a trusted publisher for the package:
+
+- Publisher: GitHub Actions
+- Organization/user: the GitHub owner
+- Repository: the repository name
+- Workflow filename: `release.yml`
+- Environment name: `npm`, if you keep the workflow environment as configured
+- Allowed action: `npm publish`
+
+Trusted Publishing requires npm CLI `11.5.1` or later and Node `22.14.0` or
+later in the publishing workflow.
+
+If Trusted Publishing cannot be used, create an npm automation token and store
+it as `NPM_TOKEN`, then update the release workflow to use that token. Prefer
+Trusted Publishing whenever possible.
+
+## Versioning
+
+Use semantic versioning:
+
+- Patch: documentation fixes, internal test changes, bug fixes that do not
+  change public behavior.
+- Minor: new props, new source forms, new supported options.
+- Major: breaking prop changes, changed defaults, removed APIs, peer range drops.
+
+Before `1.0.0`, minor releases may include breaking changes, but the changelog
+must say so clearly.
+
+## Manual Pre-Release Checklist
+
+From the package repository root:
+
+```bash
+npm install
+npm run check
+```
+
+From a consuming Expo or React Native app, when validating integration:
+
+```bash
+npm install
+npx tsc --noEmit
+npm run lint
+```
+
+Device checks:
+
+- remote `.glb` renders on Android
+- bundled `.glb` renders on Android
+- bad model URL triggers `onModelError`
+- iOS render check is completed before claiming iOS support
+
+Documentation checks:
+
+- README examples match current API
+- `docs-site/index.html` examples match current API
+- `docs-site/llms.txt` links point to public docs or GitHub URLs
+- `docs-site/sitemap.xml` and `docs-site/robots.txt` reference the canonical
+  Pages URL
+- docs-site JSON-LD matches visible content and package metadata
+- Open Graph and Twitter card metadata point to `docs-site/og-image.svg`
+- `docs/COMPATIBILITY.md` lists tested versions
+- `CHANGELOG.md` has the release entry
+- package tarball contents from `npm pack --dry-run` contain only intended files
+- GitHub Pages workflow deploys from `docs-site`
+
+## Release PR Steps
+
+1. Move `CHANGELOG.md` entries from `Unreleased` into a version heading.
+2. Update `package.json` version.
+3. Run all local checks.
+4. Open a PR.
+5. Wait for CI.
+6. Merge.
+
+## Publishing With Tags
+
+The release workflow listens for tags matching:
+
+```text
+v*
+```
+
+For version `0.1.0`:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow verifies that the tag suffix matches `package.json`'s version
+before publishing.
+
+## Publishing With workflow_dispatch
+
+The release workflow can also be started manually from GitHub Actions.
+
+Use this only after:
+
+- the version bump is already merged
+- CI is green
+- npm Trusted Publishing is configured
+
+## Post-Publish Verification
+
+After publishing:
+
+```bash
+npm view react-native-model-viewer-webview version
+npm view react-native-model-viewer-webview dist.integrity
+```
+
+Then install it in a clean Expo app:
+
+```bash
+npx create-expo-app model-viewer-publish-smoke
+cd model-viewer-publish-smoke
+npx expo install react-native-model-viewer-webview react-native-webview
+```
+
+Render the remote model from `example/App.tsx`. If the release claims bundled
+asset support, also test a local `.glb`.
+
+## Docs Site Deployment
+
+The docs site is a dependency-free static site in `docs-site`. GitHub Pages is
+deployed by `.github/workflows/pages.yml` on pushes to `main` that touch the
+docs site or Pages workflow.
+
+Before relying on the public docs link:
+
+- enable GitHub Pages with GitHub Actions as the source in repository settings
+- verify the workflow finishes successfully
+- open the Pages URL and confirm the model preview loads
+- check `docs-site/llms.txt` at the Pages root
+
+## Maintenance Rhythm
+
+Monthly or before meaningful releases:
+
+- check latest `react-native-webview` release notes
+- check Expo SDK compatibility
+- rerun Android smoke tests
+- review open issues for WebView/platform-specific failures
+- keep README limitations honest
+
+Do not expand compatibility claims based only on typechecks. Use real device
+rendering before changing support language.

package/example/App.tsx

@@ -0,0 +1,41 @@
+import { useState } from "react";
+import { SafeAreaView, Text, View } from "react-native";
+
+import {
+  ModelViewerWebView,
+  type ModelViewerStatus,
+} from "react-native-model-viewer-webview";
+
+const REMOTE_MODEL =
+  "https://modelviewer.dev/shared-assets/models/Astronaut.glb";
+
+export default function App() {
+  const [status, setStatus] = useState("Loading model...");
+
+  function handleStatus(nextStatus: ModelViewerStatus) {
+    setStatus(nextStatus.message ?? nextStatus.type);
+  }
+
+  return (
+    <SafeAreaView style={{ flex: 1, backgroundColor: "#ffffff" }}>
+      <View style={{ flex: 1, padding: 16, gap: 12 }}>
+        <Text style={{ fontSize: 20, fontWeight: "700" }}>
+          React Native Model Viewer WebView
+        </Text>
+        <ModelViewerWebView
+          modelSource={REMOTE_MODEL}
+          onStatus={handleStatus}
+          style={{ flex: 1, minHeight: 360 }}
+          htmlOptions={{
+            autoRotate: true,
+            cameraControls: true,
+            cameraOrbit: "0deg 65deg 3m",
+            exposure: 1,
+            shadowIntensity: 0.4,
+          }}
+        />
+        <Text>{status}</Text>
+      </View>
+    </SafeAreaView>
+  );
+}

package/example/README.md

@@ -0,0 +1,43 @@
+# Example
+
+This folder contains a minimal Expo screen for smoke-testing the package with a
+remote GLB.
+
+```bash
+npx create-expo-app model-viewer-example
+cd model-viewer-example
+npx expo install react-native-model-viewer-webview react-native-webview
+```
+
+Replace the generated `App.tsx` with this folder's `App.tsx`, then run:
+
+```bash
+npx expo start
+```
+
+## Testing Bundled GLB Files
+
+For local `.glb` imports, configure Metro:
+
+```js
+const { getDefaultConfig } = require("expo/metro-config");
+
+const config = getDefaultConfig(__dirname);
+
+config.resolver.assetExts = [
+  ...config.resolver.assetExts,
+  "glb",
+  "gltf",
+];
+
+module.exports = config;
+```
+
+Then use:
+
+```tsx
+<ModelViewerWebView modelSource={require("./assets/car.glb")} />
+```
+
+Always test bundled assets on a real Android or iOS device before publishing a
+release that claims bundled model support.

package/llms.txt

@@ -0,0 +1,79 @@
+# react-native-model-viewer-webview
+
+> A small React Native and Expo package for rendering simple GLB/glTF previews
+> with Google's `<model-viewer>` web component inside `react-native-webview`.
+
+Use this package when an app needs an inspectable 3D asset preview with orbit
+controls, auto-rotate, and load/error callbacks, but does not need a native 3D
+engine. For native rendering, custom scenes, shaders, physics, or AR, prefer
+Filament, React Three Fiber Native, Three.js, or Expo GLView.
+
+## Essential docs
+
+- [README](./README.md): install, quick start, props, tradeoffs, and
+  pre-publish checklist.
+- [How it works](./docs/HOW_IT_WORKS.md): WebView bridge, source resolution,
+  HTML generation, script loading, and event flow.
+- [Compatibility](./docs/COMPATIBILITY.md): peer ranges, tested versions,
+  platform notes, and limitations.
+- [Agent usage](./docs/AGENT_USAGE.md): how AI agents should consume the
+  packaged `SKILL.md`, `AGENTS.md`, and this file.
+- [Release guide](./docs/RELEASE.md): versioning, CI, npm Trusted Publishing,
+  and maintenance instructions.
+- [Contributing](./CONTRIBUTING.md): scope, checks, testing expectations, and
+  PR checklist.
+- [Security](./SECURITY.md): vulnerability reporting and support policy.
+- [Changelog](./CHANGELOG.md): release history.
+
+## Agent assets
+
+- [Package agent instructions](./AGENTS.md): stable coding-agent guidance for
+  this package.
+- [Portable Agent Skill](./agent-skills/react-native-model-viewer-webview/SKILL.md):
+  installable skill entrypoint for skills-compatible agents.
+- [Skill API reference](./agent-skills/react-native-model-viewer-webview/references/api.md):
+  compact API surface for agents.
+
+## Claude Code
+
+Claude Code can use the portable skill after it is copied or symlinked to one of
+Claude's filesystem skill locations:
+
+- `~/.claude/skills/react-native-model-viewer-webview/SKILL.md`
+- `.claude/skills/react-native-model-viewer-webview/SKILL.md`
+
+Claude Agent SDK users should load user/project setting sources and enable
+`skills="all"` or the specific `react-native-model-viewer-webview` skill.
+
+## Quick 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`.
+
+## Minimal usage
+
+```tsx
+import { ModelViewerWebView } from "react-native-model-viewer-webview";
+
+export function Preview() {
+  return (
+    <ModelViewerWebView
+      modelSource="https://example.com/model.glb"
+      style={{ height: 320 }}
+      htmlOptions={{ autoRotate: true, cameraControls: true }}
+    />
+  );
+}
+```

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "react-native-model-viewer-webview",
+  "version": "0.1.0",
+  "description": "A WebView-backed GLB and glTF model viewer for React Native and Expo.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adityabhattad2021/react-native-model-viewer-webview.git"
+  },
+  "bugs": {
+    "url": "https://github.com/adityabhattad2021/react-native-model-viewer-webview/issues"
+  },
+  "homepage": "https://adityabhattad2021.github.io/react-native-model-viewer-webview/",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "react-native": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "AGENTS.md",
+    "agent-skills",
+    "dist",
+    "example",
+    "src",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "llms.txt",
+    "README.md",
+    "SECURITY.md",
+    "docs",
+    "tsconfig.json"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "check": "npm test && npm run typecheck && npm run pack:dry-run",
+    "test": "node --test test/*.test.js",
+    "pack:dry-run": "npm pack --dry-run",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "3d",
+    "glb",
+    "gltf",
+    "model-viewer",
+    "modelviewer",
+    "3d-model",
+    "webview"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72",
+    "react-native-webview": ">=13"
+  },
+  "devDependencies": {
+    "@types/react": "~19.1.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-webview": "13.15.0",
+    "typescript": "~5.9.2"
+  }
+}