diff --git a/AGENTS.md b/AGENTS.md
index fd0373eb..2479cbba 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,8 +28,8 @@ This file provides high-signal context, architectural invariants, and authoring
| Goal | Element | Recommended Bundle | Enforced Budget |
| :--- | :--- | :--- | :---: |
-| `.glb` / `.usdz` 3D viewer + 1-tap AR handoff (no scripting) | `` | `three-live-viewer.min.js` | `< 31 KB gz` |
-| Procedural `
@@ -191,7 +191,8 @@ talks, and your code model writes the edit through an `edit_scene` tool, so edit
quality never depends on the voice model.
```html
-
@@ -256,7 +257,7 @@ material preset. The preset is the offline fallback, so the scene always renders
the same way without a network:
```html
-
+
+ "#;
+ let (_, ok_diags) = validate_scene_source(ok_html, "ok.html");
+ assert!(
+ !ok_diags.iter().any(|d| d.code == "TL401" || d.code == "TL403"),
+ "Expected zero TL401/TL403 diagnostics when capabilities are granted, got: {:?}",
+ ok_diags
+ );
+
+ let missing_html = r#"
+
+
+
+ "#;
+ let (_, diags) = validate_scene_source(missing_html, "missing.html");
+ assert!(!diags.iter().any(|d| d.code == "TL401"));
+ let tl403: Vec<&str> =
+ diags.iter().filter(|d| d.code == "TL403").map(|d| d.message.as_str()).collect();
+ assert!(tl403.iter().any(|m| m.contains("xr-hands")));
+ assert!(tl403.iter().any(|m| m.contains("shared-room")));
+ assert!(tl403.iter().any(|m| m.contains("persistent-anchors")));
+ assert!(tl403.iter().any(|m| m.contains("userData.xr.splatUrl")));
+ assert!(tl403.iter().any(|m| m.contains("userData.xr.audio.src")));
+ assert!(tl403.iter().any(|m| m.contains("userData.xr.holdToAsk")));
+
+ // Audit regressions: `texture-pack`, `xr-mode="vr"`, `allow-client-scripts` + `-scripts`
+ // negation, and multi-element HTML capability isolation.
+ let lockdown_html = r#"
+
+
+
+ "#;
+ let (_, lock_diags) = validate_scene_source(lockdown_html, "lockdown.html");
+ assert!(
+ lock_diags.iter().any(|d| d.code == "TL401"),
+ "capabilities=\"none\" must override allow-client-scripts and emit TL401"
+ );
+ assert!(lock_diags.iter().any(|d| d.code == "TL403" && d.message.contains("texture-pack")));
+ assert!(lock_diags
+ .iter()
+ .any(|d| d.code == "TL403" && d.message.contains("xr-mode=\"vr\"")));
+
+ let multi_html = r#"
+
+
+
+
+
+
+ "#;
+ let (_, multi_diags) = validate_scene_source(multi_html, "multi.html");
+ assert!(
+ multi_diags
+ .iter()
+ .any(|d| d.code == "TL403" && d.message.contains("RestrictedSplat")),
+ "Restricted sibling element must still receive TL403 even when another element has capabilities=\"all\""
+ );
+ assert!(!multi_diags.iter().any(|d| d.code == "TL403" && d.message.contains("AllowedBox")));
+ }
}
diff --git a/docs/llm-guide.md b/docs/llm-guide.md
index ebe0f5fd..c6728fd5 100644
--- a/docs/llm-guide.md
+++ b/docs/llm-guide.md
@@ -42,7 +42,7 @@ You are authoring 3D and Spatial Computing scenes using Google's `three-live` an
### 2. Procedural `
-
+
```
## Bundles
diff --git a/three-live/examples/index.html b/three-live/examples/index.html
index dadfd191..86a05d12 100644
--- a/three-live/examples/index.html
+++ b/three-live/examples/index.html
@@ -744,7 +744,7 @@ three-live AI-First Native 3D & AR
-
77.9 KB gz
+
80.9 KB gz
Zero Dependencies
WebGL2 PBR
Apple USDZ + WebXR
@@ -769,7 +769,7 @@
three-live AI-First Native 3D & AR
Connect AI Provider (Bring Your Own Account)
let voiceStopHandle = null;
// Storage helpers with window.name fallback so saved keys survive refreshes
- // on sandboxed hosts like x20web.corp.google.com (Content-Security-Policy: sandbox allow-scripts).
+ // on opaque-origin sandboxed static hosts (Content-Security-Policy: sandbox allow-scripts).
function readWindowNameStore() {
try {
const raw = window.name || "";
diff --git a/three-live/src/capabilities.ts b/three-live/src/capabilities.ts
new file mode 100644
index 00000000..5ed55d71
--- /dev/null
+++ b/three-live/src/capabilities.ts
@@ -0,0 +1,534 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {getSharedRegistry} from './plugin';
+
+/** Canonical capability names shared across Web, Android, and iOS. */
+export type ThreeLiveCapabilityName =
+ | 'scripts'
+ | 'network'
+ | 'remote_content'
+ | 'camera'
+ | 'microphone'
+ | 'sensors'
+ | 'storage'
+ | 'ai'
+ | 'external_handoff';
+
+/** Network scheme and optional origin allowlist configuration. */
+export interface ThreeLiveNetworkPolicy {
+ readonly enabled: boolean;
+ readonly schemes: ReadonlySet;
+ readonly explicitSchemes: boolean;
+ readonly origins: ReadonlySet | null;
+}
+
+/** Normalized capability policy evaluated at each sensitive access point. */
+export interface ThreeLiveCapabilities {
+ readonly scripts: boolean;
+ readonly network: ThreeLiveNetworkPolicy;
+ readonly remoteContent: boolean;
+ readonly camera: boolean;
+ readonly microphone: boolean;
+ readonly sensors: boolean;
+ readonly storage: boolean;
+ readonly ai: boolean;
+ readonly externalHandoff: boolean;
+}
+
+/** Flexible input accepted by `el.capabilities` and `ThreeLiveElement.defaultCapabilities`. */
+export interface ThreeLiveCapabilitiesInit {
+ readonly scripts?: boolean;
+ readonly network?:
+ | boolean
+ | {
+ readonly enabled?: boolean;
+ readonly schemes?: Iterable;
+ readonly explicitSchemes?: boolean;
+ readonly origins?: Iterable | null;
+ };
+ readonly remoteContent?: boolean;
+ readonly remote_content?: boolean;
+ readonly camera?: boolean;
+ readonly microphone?: boolean;
+ readonly sensors?: boolean;
+ readonly storage?: boolean;
+ readonly ai?: boolean;
+ readonly externalHandoff?: boolean;
+ readonly external_handoff?: boolean;
+}
+
+/** Non-nullable input accepted by {@link parseCapabilities} and `el.capabilities`. */
+export type ThreeLiveCapabilitiesInput =
+ | string
+ | ThreeLiveCapabilities
+ | ThreeLiveCapabilitiesInit;
+
+/** Payload delivered to `three-capability-denied` events and `onCapabilityDenied` callbacks. */
+export interface CapabilityDeniedDetail {
+ readonly capability: ThreeLiveCapabilityName;
+ readonly feature: string;
+ readonly message: string;
+ readonly url?: string;
+}
+
+type BoolCapKey = Exclude;
+
+const DEFAULT_SCHEMES: ReadonlySet = new Set(['https', 'wss']);
+const NON_NET_RE = /^(?:data|blob|asset|content|file|android\.resource):/i;
+const LOOPBACK_RE = /^(?:localhost|127\.0\.0\.1|\[::1\])$/i;
+const BOOL_KEYS: readonly BoolCapKey[] = [
+ 'scripts',
+ 'remoteContent',
+ 'camera',
+ 'microphone',
+ 'sensors',
+ 'storage',
+ 'ai',
+ 'externalHandoff',
+];
+const WIRE_TO_KEY: Readonly> = {
+ scripts: 'scripts',
+ remote_content: 'remoteContent',
+ camera: 'camera',
+ microphone: 'microphone',
+ sensors: 'sensors',
+ storage: 'storage',
+ ai: 'ai',
+ external_handoff: 'externalHandoff',
+};
+
+/** Normalizes an origin string to `scheme://host[:port]`. */
+export function normalizeCapabilityOrigin(raw: string): string | null {
+ try {
+ const u = new URL(raw.trim());
+ const s = u.protocol.slice(0, -1).toLowerCase();
+ if (!s || !u.hostname) return null;
+ const p =
+ ((s === 'https' || s === 'wss') && u.port === '443') ||
+ ((s === 'http' || s === 'ws') && u.port === '80')
+ ? ''
+ : u.port;
+ return `${s}://${u.hostname.toLowerCase()}${p ? ':' + p : ''}`;
+ } catch {
+ return null;
+ }
+}
+
+/** Sanitizes a URL for diagnostics by stripping credentials, query strings, and hashes. */
+export function sanitizeDiagnosticUrl(raw: string): string {
+ const full = raw.trim().slice(0, 8192);
+ if (NON_NET_RE.test(full)) {
+ return `${full.slice(0, full.indexOf(':') + 1)}`;
+ }
+ const basePart = full.split(/[?#]/)[0];
+ const baseHref =
+ (typeof location !== 'undefined' && location.href) || 'https://localhost/';
+ for (const candidate of [full, basePart]) {
+ try {
+ const u = new URL(candidate, baseHref);
+ u.username = u.password = u.search = u.hash = '';
+ return u.href.slice(0, 256);
+ } catch {
+ // Fall through to credential-stripping fallback.
+ }
+ }
+ return basePart
+ .replace(/\/\/[^/@\s]*@/, '//')
+ .replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/\s:@]+:[^/\s@]*/i, '$1')
+ .slice(0, 128);
+}
+
+function makeNet(
+ enabled: boolean,
+ schemes: ReadonlySet = DEFAULT_SCHEMES,
+ explicitSchemes = false,
+ origins: ReadonlySet | null = null,
+): ThreeLiveNetworkPolicy {
+ return Object.freeze({enabled, schemes, explicitSchemes, origins});
+}
+
+/** Default secure policy: all capabilities disabled. */
+export const CAPABILITIES_NONE: ThreeLiveCapabilities = Object.freeze({
+ scripts: false,
+ network: makeNet(false),
+ remoteContent: false,
+ camera: false,
+ microphone: false,
+ sensors: false,
+ storage: false,
+ ai: false,
+ externalHandoff: false,
+});
+
+/** Preset for static `.glb` / `.usdz` viewing and 1-tap AR (`viewer`). */
+export const CAPABILITIES_VIEWER: ThreeLiveCapabilities = Object.freeze({
+ ...CAPABILITIES_NONE,
+ network: makeNet(true),
+ remoteContent: true,
+ camera: true,
+ externalHandoff: true,
+});
+
+/** Preset enabling all capabilities (`all`), intended for trusted demos and playgrounds. */
+export const CAPABILITIES_ALL: ThreeLiveCapabilities = Object.freeze({
+ scripts: true,
+ network: makeNet(true),
+ remoteContent: true,
+ camera: true,
+ microphone: true,
+ sensors: true,
+ storage: true,
+ ai: true,
+ externalHandoff: true,
+});
+
+/** Parses an attribute string or init object into a normalized {@link ThreeLiveCapabilities}. */
+export function parseCapabilities(
+ input: ThreeLiveCapabilitiesInput | null | undefined,
+ base: ThreeLiveCapabilities = CAPABILITIES_NONE,
+): ThreeLiveCapabilities {
+ if (input == null) return base;
+ if (typeof input === 'string') {
+ const trimmed = input.trim();
+ if (!trimmed) return CAPABILITIES_NONE;
+ const flags: Record = {
+ scripts: base.scripts,
+ remoteContent: base.remoteContent,
+ camera: base.camera,
+ microphone: base.microphone,
+ sensors: base.sensors,
+ storage: base.storage,
+ ai: base.ai,
+ externalHandoff: base.externalHandoff,
+ };
+ let netOn = base.network.enabled;
+ let schemes = new Set(base.network.schemes);
+ let explicit = base.network.explicitSchemes;
+ let origins = base.network.origins ? new Set(base.network.origins) : null;
+ let originsSpecified = false;
+
+ for (const raw of trimmed.split(/\s+/)) {
+ if (!raw) continue;
+ const neg = raw.length > 1 && raw[0] === '-';
+ const tok = neg ? raw.slice(1) : raw;
+ const val = !neg;
+ const [head, originPart = ''] = tok.split('@');
+ const [rawName, schemePart = ''] = head.toLowerCase().split(':');
+ const name = rawName.replace(/-/g, '_');
+ if (name === 'none' && val) {
+ for (const k of BOOL_KEYS) flags[k] = false;
+ netOn = explicit = false;
+ schemes = new Set(DEFAULT_SCHEMES);
+ origins = null;
+ originsSpecified = false;
+ } else if (name === 'all' || name === '*') {
+ for (const k of BOOL_KEYS) flags[k] = val;
+ netOn = val;
+ explicit = false;
+ schemes = new Set(DEFAULT_SCHEMES);
+ origins = null;
+ originsSpecified = false;
+ } else if (name === 'viewer') {
+ netOn =
+ flags.remoteContent =
+ flags.camera =
+ flags.externalHandoff =
+ val;
+ } else if (name === 'network') {
+ netOn = val;
+ if (val && schemePart) {
+ const list = schemePart
+ .split(/[|,]/)
+ .map((s) => s.trim().replace(/:$/, ''))
+ .filter(Boolean);
+ if (list.length) {
+ schemes = new Set(list);
+ explicit = true;
+ }
+ } else if (val && !originPart) {
+ schemes = new Set(DEFAULT_SCHEMES);
+ explicit = false;
+ origins = null;
+ originsSpecified = false;
+ }
+ if (val && originPart) {
+ if (!originsSpecified) {
+ origins = new Set();
+ originsSpecified = true;
+ }
+ origins ??= new Set();
+ for (const o of originPart.split(/[|,]/)) {
+ const norm = normalizeCapabilityOrigin(o);
+ if (norm) origins.add(norm);
+ }
+ }
+ } else if (name in WIRE_TO_KEY) {
+ flags[WIRE_TO_KEY[name]] = val;
+ }
+ }
+ return {
+ ...flags,
+ network: makeNet(netOn, schemes, explicit, origins),
+ };
+ }
+
+ const init = input as ThreeLiveCapabilitiesInit;
+ let network = base.network;
+ if (typeof init.network === 'boolean') {
+ network = makeNet(init.network);
+ } else if (init.network && typeof init.network === 'object') {
+ const n = init.network;
+ const hasS = n.schemes != null;
+ const schemes = hasS
+ ? new Set(
+ Array.from(n.schemes!, (s) =>
+ s.trim().replace(/:$/, '').toLowerCase(),
+ ).filter(Boolean),
+ )
+ : new Set(base.network.schemes);
+ let origins = base.network.origins;
+ if (n.origins === null) {
+ origins = null;
+ } else if (n.origins !== undefined) {
+ const set = new Set();
+ for (const o of n.origins) {
+ const norm = normalizeCapabilityOrigin(o);
+ if (norm) set.add(norm);
+ }
+ origins = set;
+ }
+ network = makeNet(
+ n.enabled ?? true,
+ schemes,
+ n.explicitSchemes ?? hasS,
+ origins,
+ );
+ }
+ return {
+ scripts: init.scripts ?? base.scripts,
+ network,
+ remoteContent:
+ init.remoteContent ?? init.remote_content ?? base.remoteContent,
+ camera: init.camera ?? base.camera,
+ microphone: init.microphone ?? base.microphone,
+ sensors: init.sensors ?? base.sensors,
+ storage: init.storage ?? base.storage,
+ ai: init.ai ?? base.ai,
+ externalHandoff:
+ init.externalHandoff ?? init.external_handoff ?? base.externalHandoff,
+ };
+}
+
+/** Returns true when `url` uses a non-network scheme (`data:`, `blob:`, `file:`, etc.). */
+export function isNonNetworkUrl(url: string): boolean {
+ return NON_NET_RE.test(url.trim());
+}
+
+/** Checks whether `caps.network` permits connecting to `rawUrl`. */
+export function isNetworkUrlPermitted(
+ caps: ThreeLiveCapabilities,
+ rawUrl?: string,
+): boolean {
+ if (!caps.network.enabled) return false;
+ if (!rawUrl) return true;
+ const t = rawUrl.trim();
+ if (!t) return false;
+ if (isNonNetworkUrl(t)) return true;
+ try {
+ const base =
+ (typeof document !== 'undefined' && document.baseURI) ||
+ (typeof location !== 'undefined' && location.href) ||
+ 'https://localhost/';
+ const u = new URL(t, base);
+ const s = u.protocol.slice(0, -1).toLowerCase();
+ if (isNonNetworkUrl(`${s}:`)) return true;
+ const loopback =
+ (s === 'http' || s === 'ws') && LOOPBACK_RE.test(u.hostname);
+ if (
+ !caps.network.schemes.has(s) &&
+ (caps.network.explicitSchemes || !loopback)
+ ) {
+ return false;
+ }
+ if (caps.network.origins !== null) {
+ const origin = normalizeCapabilityOrigin(u.href);
+ if (!origin || !caps.network.origins.has(origin)) return false;
+ }
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/** Evaluates whether `caps` grants `capability` (and optional `url`). */
+export function hasCapabilityInPolicy(
+ caps: ThreeLiveCapabilities,
+ capability: ThreeLiveCapabilityName,
+ url?: string,
+): boolean {
+ if (capability === 'network') return isNetworkUrlPermitted(caps, url);
+ if (capability === 'remote_content') {
+ return Boolean(
+ (url && isNonNetworkUrl(url)) ||
+ (caps.remoteContent && isNetworkUrlPermitted(caps, url)),
+ );
+ }
+ if (capability === 'ai') return caps.ai && isNetworkUrlPermitted(caps, url);
+ return caps[WIRE_TO_KEY[capability]];
+}
+
+interface CapabilityHostLike {
+ __tlEl?: boolean;
+ capabilities?: ThreeLiveCapabilitiesInput | null;
+ allowClientScripts?: boolean;
+ getAttribute?: (name: string) => string | null;
+ hasAttribute?: (name: string) => boolean;
+ dispatchEvent?: (event: Event) => boolean;
+ fireEvent?: (type: string, detail?: unknown) => void;
+ onCapabilityDenied?: ((detail: CapabilityDeniedDetail) => void) | null;
+ __tlCapsOverride?: ThreeLiveCapabilities | null;
+ __tlCapsInit?: ThreeLiveCapabilitiesInit | null;
+}
+
+const deniedDedup = new WeakMap