create-playcanvas 0.12.0 → 0.13.0

package/README.md

@@ -50,7 +50,7 @@ The `web-lens` starter is a portrait game ready to publish to Snapchat as a [Web
 npm create playcanvas@latest my-lens -- --starter web-lens
 ```
 
-Its `npm run package` script builds the game, checks it against the Web Lens upload rules (size limits, relative paths and no network access) and writes the zip to upload through [My Lenses](https://my-lenses.snapchat.com/).
+Its `npm run package` script builds the game, checks it against the Web Lens upload rules (size limits, relative paths, no network access and no camera or microphone) and writes the zip to upload through [My Lenses](https://my-lenses.snapchat.com/).
 
 ## CLI Options
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-playcanvas",
-    "version": "0.12.0",
+    "version": "0.13.0",
     "description": "Scaffold a PlayCanvas project",
     "keywords": [
         "playcanvas",
@@ -44,7 +44,7 @@
     },
     "devDependencies": {
         "@clack/prompts": "^1.8.1",
-        "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/eslint-config": "3.0.0",
         "@types/node": "22.20.5",
         "eslint": "^9.39.5",
         "mri": "^1.2.0",

package/templates/_shared/web-lens/AGENTS.md

@@ -5,6 +5,9 @@ This project is a Snapchat Web Lens: Snapchat runs it in a sandbox, from an uplo
 - Run `npm run package` after a change. It builds into `dist/lens/`, checks the build against the Web Lens upload rules and writes the zip to `dist/`, or reports why it wrote none.
 - A Lens can't reach the network. Bundle every asset into the build, and load nothing from another host, such as a script from a CDN, a web font or a remote model.
 - The zip must stay under 8 MB and `index.html` under 1 MB.
+- Snapchat disables the camera and microphone for Web Lenses. Keep `getUserMedia`, `getDisplayMedia` and `ImageCapture` out of the build entirely.
+- Motion sensors, geolocation, payments, MIDI, USB and WebRTC are off too, so design for pointer input.
+- `localStorage` and IndexedDB start empty every time the Lens opens. To keep data between launches, use the Web Lens API's [storage](https://developers.snap.com/web-lenses/storage), `snapchat.storage`: check `snapchat.isSupported('storage')` after `init()` resolves, write nothing until the first read answers, and chain writes through one promise. Each value can be up to 32 KiB, and the whole store 100 KiB. `src/lens.ts` keeps the best score this way.
 - `npm run start` serves the build under the Lens sandbox's rules, so a request that would fail in Snapchat also fails in the browser console.
 - `src/lens.ts` is the only code that talks to Snapchat. Outside Snapchat, the Web Lens API answers from a stub with canned data, so the game runs in any browser. Call `recordScore(score)` when a run ends.
 - Keep the layout portrait and the HUD inside the safe area, using the `--inset-*` properties from `src/lens.css`.

package/templates/_shared/web-lens/README.md

@@ -18,8 +18,9 @@ This builds the game into `dist/lens/`, checks it against the [Web Lens upload r
 - the build refers to one of its own files by an absolute path, such as `/assets/game.js`
 - the build loads anything from another host, such as a script from a CDN or a web font
 - the build uses something the Lens sandbox blocks, such as an `<iframe>` or a web app manifest
+- the build's code asks for the camera, microphone or screen (`getUserMedia`, `getDisplayMedia` or `ImageCapture`), which Snapchat disables for Web Lenses
 
-It warns about any other host your scripts mention, since a Lens can't reach the network. To check the build itself, `npm run start` serves it under the same rules, so a request for anything outside the zip fails in the browser console as it would in Snapchat.
+It warns about any other host your scripts mention, since a Lens can't reach the network. It also warns about code that uses something Snapchat [turns off for Web Lenses](https://developers.snap.com/web-lenses/capabilities): motion sensors, geolocation, payments, MIDI, USB and WebRTC, and `localStorage` or IndexedDB, which start empty every time the Lens opens, so keep data between launches with the Web Lens API's [storage](https://developers.snap.com/web-lenses/storage) instead. To check the build itself, `npm run start` serves it under the same rules, so a request for anything outside the zip, or for a device such as the camera, fails in the browser console as it would in Snapchat.
 
 ### How it fits together
 

package/templates/_shared/web-lens/scripts/package-lens.mjs

@@ -19,6 +19,32 @@ const BLOCKED_TAGS = ['base', 'embed', 'iframe', 'object'];
 // error messages link to
 const TEXT_HOSTS = ['www.w3.org', 'github.com', 'react.dev', 'api.playcanvas.com'];
 
+// APIs that open the camera, microphone or screen, which Snapchat disables for Web Lenses
+const CAPTURE_APIS =
+    /\b(?:mediaDevices|getUserMedia|webkitGetUserMedia|mozGetUserMedia|getDisplayMedia|ImageCapture)\b/g;
+
+// other features Snapchat turns off for Web Lenses: code that relies on them gets nothing, so it's
+// worth a look rather than a failure
+const UNAVAILABLE_APIS = [
+    {
+        pattern:
+            /\b(?:deviceorientation|devicemotion|DeviceOrientationEvent|DeviceMotionEvent|Accelerometer|Gyroscope|Magnetometer|LinearAccelerationSensor|GravitySensor|AbsoluteOrientationSensor|RelativeOrientationSensor)\b/g,
+        reason: 'Motion sensors are off in a Web Lens, so design for pointer input rather than tilt'
+    },
+    {
+        pattern: /\b(?:geolocation|PaymentRequest|requestMIDIAccess|navigator\.usb)\b/g,
+        reason: 'Geolocation, payments, MIDI and USB are off in a Web Lens'
+    },
+    {
+        pattern: /\bRTC(?:PeerConnection|DataChannel)\b/g,
+        reason: "A Web Lens can't make WebRTC connections"
+    },
+    {
+        pattern: /\b(?:localStorage|indexedDB)\b/g,
+        reason: "localStorage and IndexedDB start empty every time the Lens opens, so keep data between launches with the Web Lens API's storage (snapchat.storage)"
+    }
+];
+
 const buildDir = path.resolve(process.argv[2] ?? 'dist/lens');
 const { name = 'web-lens' } = JSON.parse(fs.readFileSync('package.json', 'utf8'));
 const zipFile = path.join(path.dirname(buildDir), `${name.replace(/^@/, '').replace('/', '-')}.zip`);
@@ -134,6 +160,32 @@ for (const file of files.filter((f) => /\.m?js$/.test(f))) {
     }
 }
 
+// where `pattern` first matches in `source`, as line:column, and every API name it matched
+const findUses = (source, pattern) => {
+    const uses = Array.from(source.matchAll(pattern));
+    if (!uses.length) return null;
+    const before = source.slice(0, uses[0].index);
+    return {
+        at: `${before.split('\n').length}:${uses[0].index - before.lastIndexOf('\n')}`,
+        apis: [...new Set(uses.map(([api]) => api))].join(', ')
+    };
+};
+
+// features a Lens can't use, in scripts or inline in markup
+for (const file of files.filter((f) => /\.(?:html|m?js)$/.test(f))) {
+    const source = read(file);
+    const capture = findUses(source, CAPTURE_APIS);
+    if (capture) {
+        errors.push(
+            `${file}:${capture.at}: uses ${capture.apis}. Snapchat disables the camera and microphone for Web Lenses, so remove the capture code`
+        );
+    }
+    for (const { pattern, reason } of UNAVAILABLE_APIS) {
+        const use = findUses(source, pattern);
+        if (use) warnings.push(`${file}:${use.at}: uses ${use.apis}. ${reason}`);
+    }
+}
+
 // a plain zip: deflated entries with forward-slash names and index.html at the root
 const zipEntries = (entries) => {
     const local = [];

package/templates/engine/base/AGENTS.md

@@ -10,6 +10,7 @@ A PlayCanvas Engine app in TypeScript, built with Vite. The scene is built in co
 - `npm run lint` runs ESLint, and `npm run lint:fix` fixes what it can.
 - `npm run fmt` checks formatting, and `npm run fmt:fix` applies Prettier.
 - `npm run build` builds the production site into `dist/`, and `npm run start` serves it.
+- `npm run dev` and `npm run start` open the page in the default browser.
 
 ## Layout
 

package/templates/engine/base/README.md

@@ -13,7 +13,7 @@ npm install
 npm run dev
 ```
 
-Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
+The app opens in your browser at <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
 ## Inspector
 
@@ -23,14 +23,14 @@ Open <http://localhost:5173>. Edit the files under `src/` and save to see the sc
 
 Run these with `npm run <script>`:
 
-| Script      | Description                       |
-| ----------- | --------------------------------- |
-| `dev`       | Start the Vite development server |
-| `build`     | Build for production              |
-| `start`     | Preview the production build      |
-| `lint`      | Run ESLint                        |
-| `fmt`       | Check formatting                  |
-| `typecheck` | Run TypeScript checks             |
+| Script      | Description                                        |
+| ----------- | -------------------------------------------------- |
+| `dev`       | Start the Vite development server and open the app |
+| `build`     | Build for production                               |
+| `start`     | Preview the production build and open the app      |
+| `lint`      | Run ESLint                                         |
+| `fmt`       | Check formatting                                   |
+| `typecheck` | Run TypeScript checks                              |
 
 Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 

package/templates/engine/base/package.json

@@ -6,19 +6,19 @@
     "type": "module",
     "scripts": {
         "build": "vite build",
-        "dev": "vite",
+        "dev": "vite --open",
         "fmt": "prettier --check .",
         "fmt:fix": "prettier --write .",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
-        "start": "vite preview",
+        "start": "vite preview --open",
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
         "playcanvas": "^2.23.3"
     },
     "devDependencies": {
-        "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/eslint-config": "3.0.0",
         "@playcanvas/inspector": "^0.4.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.10",

package/templates/engine/web-lens/vite.config.ts

@@ -11,6 +11,21 @@ const LENS_SANDBOX = [
     "form-action 'none'"
 ].join('; ');
 
+// Approximates its permissions policy, which turns off device features such as the camera and
+// motion sensors
+const LENS_PERMISSIONS = [
+    'camera=()',
+    'microphone=()',
+    'display-capture=()',
+    'accelerometer=()',
+    'gyroscope=()',
+    'magnetometer=()',
+    'geolocation=()',
+    'payment=()',
+    'usb=()',
+    'midi=()'
+].join(', ');
+
 // https://vite.dev/config/
 export default defineConfig({
     // Snapchat serves a Lens from its own origin, so every URL in the build must be relative
@@ -25,10 +40,11 @@ export default defineConfig({
         chunkSizeWarningLimit: 3000
     },
     preview: {
-        // npm run start serves the build under the Lens rules, so a request for anything outside
-        // the zip fails in the browser console as it would in Snapchat
+        // npm run start serves the build under the Lens rules, so loading anything from outside the
+        // zip, or using a device such as the camera, fails in the browser as it would in Snapchat
         headers: {
             'Content-Security-Policy': LENS_SANDBOX,
+            'Permissions-Policy': LENS_PERMISSIONS,
             'Cross-Origin-Opener-Policy': 'same-origin',
             'Cross-Origin-Embedder-Policy': 'require-corp'
         }

package/templates/react/base/AGENTS.md

@@ -10,6 +10,7 @@ A PlayCanvas app in TypeScript and React, built with Vite. The scene is declared
 - `npm run lint` runs ESLint, and `npm run lint:fix` fixes what it can.
 - `npm run fmt` checks formatting, and `npm run fmt:fix` applies Prettier.
 - `npm run build` builds the production site into `dist/`, and `npm run start` serves it.
+- `npm run dev` and `npm run start` open the page in the default browser.
 
 ## Layout
 

package/templates/react/base/README.md

@@ -13,7 +13,7 @@ npm install
 npm run dev
 ```
 
-Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
+The app opens in your browser at <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
 ## Inspector
 
@@ -23,14 +23,14 @@ Open <http://localhost:5173>. Edit the files under `src/` and save to see the sc
 
 Run these with `npm run <script>`:
 
-| Script      | Description                       |
-| ----------- | --------------------------------- |
-| `dev`       | Start the Vite development server |
-| `build`     | Build for production              |
-| `start`     | Preview the production build      |
-| `lint`      | Run ESLint                        |
-| `fmt`       | Check formatting                  |
-| `typecheck` | Run TypeScript checks             |
+| Script      | Description                                        |
+| ----------- | -------------------------------------------------- |
+| `dev`       | Start the Vite development server and open the app |
+| `build`     | Build for production                               |
+| `start`     | Preview the production build and open the app      |
+| `lint`      | Run ESLint                                         |
+| `fmt`       | Check formatting                                   |
+| `typecheck` | Run TypeScript checks                              |
 
 Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 

package/templates/react/base/eslint.config.mjs

@@ -1,15 +1,4 @@
 import reactConfig from '@playcanvas/eslint-config/react';
 import typescriptConfig from '@playcanvas/eslint-config/typescript';
 
-export default [
-    { ignores: ['.claude', '.agents', 'public/ammo'] },
-    ...typescriptConfig,
-    ...reactConfig,
-    {
-        rules: {
-            'react/jsx-uses-react': 'off',
-            'react/prop-types': 'off',
-            'react/react-in-jsx-scope': 'off'
-        }
-    }
-];
+export default [{ ignores: ['.claude', '.agents', 'public/ammo'] }, ...typescriptConfig, ...reactConfig];

package/templates/react/base/package.json

@@ -6,12 +6,12 @@
     "type": "module",
     "scripts": {
         "build": "vite build",
-        "dev": "vite",
+        "dev": "vite --open",
         "fmt": "prettier --check .",
         "fmt:fix": "prettier --write .",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
-        "start": "vite preview",
+        "start": "vite preview --open",
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
@@ -21,7 +21,7 @@
         "react-dom": "^19.3.1"
     },
     "devDependencies": {
-        "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/eslint-config": "3.0.0",
         "@playcanvas/inspector": "^0.4.0",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",

package/templates/react/web-lens/vite.config.ts

@@ -12,6 +12,21 @@ const LENS_SANDBOX = [
     "form-action 'none'"
 ].join('; ');
 
+// Approximates its permissions policy, which turns off device features such as the camera and
+// motion sensors
+const LENS_PERMISSIONS = [
+    'camera=()',
+    'microphone=()',
+    'display-capture=()',
+    'accelerometer=()',
+    'gyroscope=()',
+    'magnetometer=()',
+    'geolocation=()',
+    'payment=()',
+    'usb=()',
+    'midi=()'
+].join(', ');
+
 // https://vite.dev/config/
 export default defineConfig({
     // Snapchat serves a Lens from its own origin, so every URL in the build must be relative
@@ -26,10 +41,11 @@ export default defineConfig({
         chunkSizeWarningLimit: 3000
     },
     preview: {
-        // npm run start serves the build under the Lens rules, so a request for anything outside
-        // the zip fails in the browser console as it would in Snapchat
+        // npm run start serves the build under the Lens rules, so loading anything from outside the
+        // zip, or using a device such as the camera, fails in the browser as it would in Snapchat
         headers: {
             'Content-Security-Policy': LENS_SANDBOX,
+            'Permissions-Policy': LENS_PERMISSIONS,
             'Cross-Origin-Opener-Policy': 'same-origin',
             'Cross-Origin-Embedder-Policy': 'require-corp'
         }

package/templates/web-components/base/AGENTS.md

@@ -10,6 +10,7 @@ A PlayCanvas app in TypeScript, built with Vite. The scene is declared in HTML w
 - `npm run lint` runs ESLint, and `npm run lint:fix` fixes what it can.
 - `npm run fmt` checks formatting, and `npm run fmt:fix` applies Prettier.
 - `npm run build` builds the production site into `dist/`, and `npm run start` serves it.
+- `npm run dev` and `npm run start` open the page in the default browser.
 
 ## Layout
 

package/templates/web-components/base/README.md

@@ -14,7 +14,7 @@ npm install
 npm run dev
 ```
 
-Open <http://localhost:5173>. Edit `index.html` to change the scene.
+The app opens in your browser at <http://localhost:5173>. Edit `index.html` to change the scene.
 
 ## Inspector
 
@@ -24,14 +24,14 @@ Open <http://localhost:5173>. Edit `index.html` to change the scene.
 
 Run these with `npm run <script>`:
 
-| Script      | Description                       |
-| ----------- | --------------------------------- |
-| `dev`       | Start the Vite development server |
-| `build`     | Build for production              |
-| `start`     | Preview the production build      |
-| `lint`      | Run ESLint                        |
-| `fmt`       | Check formatting                  |
-| `typecheck` | Run TypeScript checks             |
+| Script      | Description                                        |
+| ----------- | -------------------------------------------------- |
+| `dev`       | Start the Vite development server and open the app |
+| `build`     | Build for production                               |
+| `start`     | Preview the production build and open the app      |
+| `lint`      | Run ESLint                                         |
+| `fmt`       | Check formatting                                   |
+| `typecheck` | Run TypeScript checks                              |
 
 Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 

package/templates/web-components/base/package.json

@@ -6,12 +6,12 @@
     "type": "module",
     "scripts": {
         "build": "vite build",
-        "dev": "vite",
+        "dev": "vite --open",
         "fmt": "prettier --check .",
         "fmt:fix": "prettier --write .",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
-        "start": "vite preview",
+        "start": "vite preview --open",
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
@@ -19,7 +19,7 @@
         "playcanvas": "^2.23.3"
     },
     "devDependencies": {
-        "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/eslint-config": "3.0.0",
         "@playcanvas/inspector": "^0.4.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.10",

package/templates/web-components/web-lens/vite.config.ts

@@ -11,6 +11,21 @@ const LENS_SANDBOX = [
     "form-action 'none'"
 ].join('; ');
 
+// Approximates its permissions policy, which turns off device features such as the camera and
+// motion sensors
+const LENS_PERMISSIONS = [
+    'camera=()',
+    'microphone=()',
+    'display-capture=()',
+    'accelerometer=()',
+    'gyroscope=()',
+    'magnetometer=()',
+    'geolocation=()',
+    'payment=()',
+    'usb=()',
+    'midi=()'
+].join(', ');
+
 // https://vite.dev/config/
 export default defineConfig({
     // Snapchat serves a Lens from its own origin, so every URL in the build must be relative
@@ -25,10 +40,11 @@ export default defineConfig({
         chunkSizeWarningLimit: 3000
     },
     preview: {
-        // npm run start serves the build under the Lens rules, so a request for anything outside
-        // the zip fails in the browser console as it would in Snapchat
+        // npm run start serves the build under the Lens rules, so loading anything from outside the
+        // zip, or using a device such as the camera, fails in the browser as it would in Snapchat
         headers: {
             'Content-Security-Policy': LENS_SANDBOX,
+            'Permissions-Policy': LENS_PERMISSIONS,
             'Cross-Origin-Opener-Policy': 'same-origin',
             'Cross-Origin-Embedder-Policy': 'require-corp'
         }