Engineering a Browser-First Metaverse: WebXR Fallbacks, Server-Authoritative Rooms, and Versioned Scene Manifests
The MyZubster Metaverse is being developed as a browser-first platform rather than a VR-only application.
Our baseline requirement is straightforward:
A user must be able to access the experience from a normal desktop or mobile browser. WebXR should enhance the experience when available, but its absence must never block access.
During the latest development cycle, we implemented two foundational components:
- A browser and WebXR capability-detection layer with graceful fallback
- A versioned scene-manifest contract validated by the backend before publication
This article explains the architecture, implementation details, validation rules, current production evidence, and the remaining roadmap.
Project Links
- Repository: MyZubster-Ecosystem/myzubster
- Live Metaverse: myzubster.com/metaverse
- WebXR fallback: Pull Request #1597
- Scene-manifest validation: Pull Request #1601
- LIFE Pilot entry point: myzubster.com/life-pilot
System Architecture
The current metaverse architecture separates device capabilities, presentation, room authority, scene configuration, and evidence.
┌─────────────────────────────────────────────────────────┐
│ React Browser UI │
│ │
│ Capability checks → status UI → browser/WebXR fallback │
└────────────────────────────┬────────────────────────────┘ │
▼
┌─────────────────────────────────────────────────────────┐
│ Metaverse Client Runtime │
│ │
│ Scene loading → controls → chat → emotes → interactions │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Server-Authoritative API │
│ │
│ Rooms → sessions → access → capacity → stage → tokens │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Versioned Scene Contract │
│ │
│ Assets → spawn points → zones → portals → capabilities │
└────────────────────────────┬────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ LIFE Evidence Layer │
│ │
│ Pilot → provenance → evidence → KPI/MRV → visualization │
└─────────────────────────────────────────────────────────┘
The separation creates several important boundaries:
- The browser reports its capabilities.
- The server decides whether a room transition is valid.
- The manifest describes what the client may load.
- The evidence layer determines what real-world claims can be displayed.
- The 3D client is never the authority for authentication or environmental evidence.
What Currently Works
Neon Plaza can be entered through a normal browser without installing a native application or connecting a VR headset.
In a production desktop smoke test, we verified:
- Authenticated access
- Character-associated entry
- Neon Plaza loading
- An active online session
- Movement controls
- Emotes
- Room chat
- Browser capability detection
- Non-blocking fallback when immersive WebXR is unavailable
This was a desktop production verification. Real mobile devices and physical WebXR headsets still require a structured validation matrix.
Part 1: Browser and WebXR Capability Detection
The first milestone was implemented in PR #1597.
Explicit WebXR States
WebXR availability is not represented as a simple boolean.
export const WEBXR_STATUS = Object.freeze({
CHECKING: 'checking',
SUPPORTED: 'supported',
UNSUPPORTED: 'unsupported',
ERROR: 'error'
});
This distinguishes between four different conditions:
checking
│
├── supported
├── unsupported
└── error
A browser that does not expose navigator.xr is different from a browser that exposes the API but fails during capability detection.
That distinction is useful for both debugging and user communication.
Browser Baseline
The client checks a small browser baseline independently of WebXR:
export function browserCapabilityBaseline(browser = window) {
return [
{
label: 'JavaScript',
ok: true
},
{
label: 'Fetch API',
ok: typeof browser.fetch === 'function'
},
{
label: 'Local storage',
ok: Boolean(browser.localStorage)
},
{
label: 'CSS Grid',
ok: Boolean(
browser.CSS?.supports?.('display', 'grid')
)
},
{
label: 'Connection',
ok: browser.navigator?.onLine !== false
}
];
}
WebXR is checked separately because it is an enhancement rather than a baseline dependency.
Detecting Immersive VR
The detection function accepts a navigator-like dependency:
export async function detectImmersiveVr(
navigatorLike = navigator
) {
if (!navigatorLike?.xr?.isSessionSupported) {
return {
status: WEBXR_STATUS.UNSUPPORTED,
reason: 'api-unavailable'
};
}
try {
const supported =
await navigatorLike.xr.isSessionSupported(
'immersive-vr'
);
return {
status: supported
? WEBXR_STATUS.SUPPORTED
: WEBXR_STATUS.UNSUPPORTED,
reason: supported
? null
: 'session-unsupported'
};
} catch (_error) {
return {
status: WEBXR_STATUS.ERROR,
reason: 'capability-check-failed'
};
}
}
Passing navigatorLike as an argument makes the function easier to test.
For example:
const fakeNavigator = {
xr: {
isSessionSupported: async (mode) =>
mode === 'immersive-vr'
}
};
const result =
await detectImmersiveVr(fakeNavigator);
expect(result.status).toBe('supported');
The unsupported case can also be tested without a real headset:
const result =
await detectImmersiveVr({});
expect(result).toEqual({
status: 'unsupported',
reason: 'api-unavailable'
});
Non-Blocking Fallback
The UI maps the capability state to a user-facing message:
const XR_COPY = {
[WEBXR_STATUS.CHECKING]:
'Checking WebXR support…',
[WEBXR_STATUS.SUPPORTED]:
'Immersive WebXR is available',
[WEBXR_STATUS.UNSUPPORTED]:
'Browser mode active: a headset is not required',
[WEBXR_STATUS.ERROR]:
'WebXR could not be verified: continue in browser mode'
};
The important behavior is that an unsupported or failed WebXR check does not produce a fatal application state.
{xr.status !== WEBXR_STATUS.SUPPORTED && (
Neon Plaza remains accessible from desktop and mobile.
The WebXR check never blocks entry.
)}
The capability model therefore follows progressive enhancement:
Standard browser
↓
Browser-based Neon Plaza
↓
Optional capabilities
├── WebGL enhancements
├── spatial audio
├── immersive WebXR
└── headset controllers
Part 2: Server-Authoritative Room State
The metaverse room lifecycle is enforced by the backend rather than trusted to client-side state.
Forward-Only State Machine
The backend defines valid transitions:
const ROOM_TRANSITIONS = Object.freeze({
draft: new Set(['published']),
published: new Set(['scheduled', 'live']),
scheduled: new Set(['live']),
live: new Set(['ended']),
ended: new Set(['archive']),
archive: new Set([])
});
The resulting lifecycle is:
draft
│
▼
published
│
├──────────────┐
▼ ▼
scheduled live
│ │
└──────►───────┘
▼
ended
│
▼
archive
The backend rejects invalid transitions:
if (
patch.state &&
patch.state !== room.state
) {
const allowed =
ROOM_TRANSITIONS[room.state]?.has(patch.state);
if (!allowed) {
return {
valid: false,
status: 409,
error:
`Invalid room transition ` +
`${room.state} -> ${patch.state}`
};
}
room.state = patch.state;
}
A modified browser therefore cannot return an ended room to the live state simply by changing its local representation.
Access Policies
Rooms support three access policies:
accessPolicy: {
type: String,
enum: [
'public',
'authenticated',
'private'
],
default: 'authenticated'
}
The room model also includes bounded capacity:
capacity: {
type: Number,
min: 1,
max: 500,
default: 100
}
Join Validation
Before joining, the backend checks session state, blocklists, private-room access, and capacity:
async function validateJoin({
session,
room,
actorUserId
}) {
if (session.state !== 'live') {
return {
valid: false,
status: 409,
error: 'Session is not live'
};
}
const actor = String(actorUserId);
if ((room.blockedUserIds || []).includes(actor)) {
return {
valid: false,
status: 403,
error: 'Access blocked'
};
}
const privateAccessDenied =
room.accessPolicy === 'private' &&
!(room.allowedUserIds || []).includes(actor) &&
actor !== String(room.hostUserId);
if (privateAccessDenied) {
return {
valid: false,
status: 403,
error: 'Private room access denied'
};
}
const current =
new Set(session.participantUserIds || []);
const capacityReached =
!current.has(actor) &&
current.size >= session.capacity;
if (capacityReached) {
return {
valid: false,
status: 409,
error: 'Session is at capacity'
};
}
return { valid: true };
}
This is important because client-side room membership cannot be considered authoritative.
Part 3: Realtime Session Tokens
After a successful join, the backend issues a short-lived token scoped to the metaverse session.
function mintRealtimeToken(
session,
actorUserId
) {
const secret =
process.env.REALTIME_TOKEN_SECRET ||
process.env.JWT_SECRET;
if (!secret) {
throw new Error(
'Realtime token secret is not configured'
);
}
return jwt.sign({
sub: String(actorUserId),
purpose: 'metaverse-realtime',
sessionId: session.sessionId,
roomId: session.roomId,
sceneManifestVersion:
session.sceneManifestVersion
}, secret, {
expiresIn: '5m'
});
}
The token binds the connection to:
- A user
- A specific purpose
- A session
- A room
- A scene-manifest version
Using a dedicated purpose value reduces the risk of using a generic application token in the wrong context.
The short expiration also limits the useful lifetime of a captured realtime credential.
Future work will include:
- Token refresh
- Explicit revocation
- Reconnect behavior
- Redis-backed realtime coordination
- Horizontal scaling
- Multi-region latency handling
Replay-resistance analysis
Part 4: Privacy-Aware Moderation References
Moderation interfaces do not need to expose raw account IDs.
The backend generates opaque session-scoped participant references:
function moderationParticipantRef(
sessionId,
actorUserId
) {
return hashRoomInviteCode(
${sessionId}:${actorUserId}
).slice(0, 24);
}
Room blocklist references are scoped separately:
function blockedParticipantRef(
roomId,
actorUserId
) {
return hashRoomInviteCode(
blocklist:${roomId}:${actorUserId}
).slice(0, 24);
}
The public session response returns a count rather than the participant-ID array:
function publicSession(session) {
return {
id: session.sessionId,
roomId: session.roomId,
state: session.state,
capacity: session.capacity,
participantCount:
(session.participantUserIds || []).length,
sceneManifestVersion:
session.sceneManifestVersion,
lifecycleVersion:
session.lifecycleVersion,
startedAt: session.startedAt || null,
endedAt: session.endedAt || null
};
}
This does not provide anonymity by itself, but it limits unnecessary identifier exposure.
Part 5: Versioned Scene Manifest v1
The next milestone was delivered in PR #1601.
The manifest is the contract between:
- Room configuration
- Backend validation
- Client runtime
- Asset delivery
- Capability requirements
- Future rollback behavior
Supported Contract Values
const SCENE_MANIFEST_SCHEMA_VERSION = '1';
const ASSET_TYPES = new Set([
'gltf',
'glb',
'image',
'audio',
'video'
]);
const ZONE_TYPES = new Set([
'portal',
'stage',
'link'
]);
const LIGHTING_PRESETS = new Set([
'day',
'sunset',
'night',
'studio'
]);
const CAPABILITIES = new Set([
'webgl2',
'webxr-immersive-vr',
'audio',
'video'
]);
The schema is deliberately constrained.
An unrestricted JSON document would make compatibility, validation, migration, and rollback increasingly difficult.
Safe Default Manifest
New rooms receive a minimal valid scene definition:
function defaultSceneManifest() {
return {
schemaVersion:
SCENE_MANIFEST_SCHEMA_VERSION,
assetBundleVersion: '1',
assets: [],
spawnPoints: [
{
id: 'default',
position: [0, 0, 0]
}
],
interactionZones: [],
stage: {
position: [0, 0, 0],
capacity: 1
},
lighting: {
preset: 'day'
},
capabilities: []
};
}
The room creation service applies it automatically:
const room = await VirtualRoom.create({
roomId: crypto.randomUUID(),
slug: safeSlug,
name: safeName,
hostUserId: String(actorUserId),
accessPolicy,
capacity: numericCapacity,
stagePolicy,
sceneManifest: defaultSceneManifest()
});
This avoids creating rooms with an undefined scene state.
Example Scene Manifest
A more complete manifest could look like this:
{
"schemaVersion": "1",
"assetBundleVersion": "42",
"assets": [
{
"id": "neon-plaza",
"type": "glb",
"url": "https://cdn.myzubster.com/scenes/neon-plaza.42.glb"
},
{
"id": "ambient-audio",
"type": "audio",
"url": "https://cdn.myzubster.com/audio/neon-plaza.7.ogg"
},
{
"id": "life-dashboard",
"type": "image",
"url": "https://cdn.myzubster.com/life/dashboard.12.webp"
}
],
"spawnPoints": [
{
"id": "main-entrance",
"position": [0, 1.6, 4]
},
{
"id": "life-hub",
"position": [12, 1.6, -3]
}
],
"interactionZones": [
{
"id": "life-portal",
"type": "portal",
"position": [10, 0, -3],
"radius": 1.5,
"destination": "life-hub"
},
{
"id": "pilot-details",
"type": "link",
"position": [14, 1, -4],
"radius": 1,
"destination": "https://www.myzubster.com/life-pilot"
}
],
"stage": {
"position": [0, 0, -8],
"capacity": 30
},
"lighting": {
"preset": "sunset"
},
"capabilities": [
"webgl2",
"audio"
]
}
The manifest contains only declarative scene information. It does not grant permissions or override room authority.
Part 6: Manifest Validation
Identifier Validation
Identifiers use a restricted character set:
function validId(value) {
return (
typeof value === 'string' &&
/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value)
);
}
This avoids IDs containing markup, control characters, or unexpected path syntax.
Vector Validation
Positions must contain exactly three finite values:
function validVector(value) {
return (
Array.isArray(value) &&
value.length === 3 &&
value.every(Number.isFinite)
);
}
These values are invalid:
[0, 1]
[0, 1, null]
[0, 1, NaN]
[0, 1, Infinity]
HTTPS-Only URLs
External resources must use HTTPS:
function validHttpsUrl(value) {
if (
typeof value !== 'string' ||
value.length > 2048
) {
return false;
}
try {
return new URL(value).protocol === 'https:';
} catch {
return false;
}
}
This rejects examples such as:
http://example.com/scene.glb
javascript:alert(1)
invalid-url
HTTPS is only the first boundary. Future validation should also enforce:
- Approved asset origins
- Content-Type checks
- Download timeouts
- File-size limits
- Redirect restrictions
- Content hashes
- glTF structural validation
- Geometry budgets
- Texture budgets
- CORS requirements
Bounded Collections
Manifest collections are explicitly bounded:
if (
!Array.isArray(input.assets) ||
input.assets.length > 100
) {
errors.push(
'assets must be an array with at most 100 entries'
);
}
Spawn points require at least one entry and allow a maximum of 32:
if (
!Array.isArray(input.spawnPoints) ||
input.spawnPoints.length < 1 ||
input.spawnPoints.length > 32
) {
errors.push(
'spawnPoints must contain between 1 and 32 entries'
);
}
These limits reduce accidental or malicious resource amplification before the runtime even begins downloading scene assets.
Part 7: Publication Gate
A scene is validated when its manifest is updated and again when the room is published.
const manifestCandidate =
patch.sceneManifest !== undefined
? patch.sceneManifest
: room.sceneManifest;
if (
patch.sceneManifest !== undefined ||
patch.state === 'published'
) {
const validation =
validateSceneManifest(manifestCandidate);
if (!validation.valid) {
return {
valid: false,
status: 400,
error: 'Invalid scene manifest',
details: validation.errors
};
}
room.sceneManifest =
validation.manifest;
}
This establishes an important invariant:
Invalid scene manifest
│
▼
Backend validation failure
│
▼
Publication rejected
The frontend may eventually provide immediate validation feedback, but frontend checks are not authoritative.
An API consumer could bypass the official interface. The backend must enforce the contract independently.
Part 8: Persistence Model
The room currently stores:
sceneManifestVersion: {
type: String,
default: '1'
},
sceneManifest: {
type: mongoose.Schema.Types.Mixed,
default: null
}
The public room response includes both fields:
function publicRoom(room) {
return {
id: room.roomId,
slug: room.slug,
name: room.name,
state: room.state,
accessPolicy: room.accessPolicy,
capacity: room.capacity,
stagePolicy: room.stagePolicy,
sceneManifestVersion:
room.sceneManifestVersion,
sceneManifest:
room.sceneManifest || null,
scheduledFor:
room.scheduledFor || null
};
}
This is sufficient for the current validation milestone, but the next persistence model should introduce immutable historical versions.
Part 9: Automated Tests
The manifest tests cover:
- The safe default manifest
- Versioned asset bundles
- HTTPS asset references
- Valid spawn points
- Valid interaction zones
- Portal destinations
- Unsupported schema versions
- Insecure URLs
- Malformed vectors
- Duplicate IDs
Unsupported capabilities
Example:
test(
'rejects unsupported schema versions and insecure asset URLs',
() => {
const manifest = {
...defaultSceneManifest(),
schemaVersion: '2',
assets: [{
id: 'plaza',
type: 'glb',
url: 'http://cdn.example.com/plaza.glb'
}]
};
const result =
validateSceneManifest(manifest);
expect(result.valid).toBe(false);
expect(result.errors).toEqual(
expect.arrayContaining([
'schemaVersion must be 1',
'assets[0].url must use https'
])
);
}
);
The implementation passed:
- Backend lint
- Backend unit tests
- Frontend unit tests
- Backend build
- Frontend build
- Security audit
- Continuous evidence checks
Production Evidence and Current Limits
The following behavior was verified against the production desktop experience:
- Authentication was active
- Neon Plaza loaded
- The session appeared online
- Movement controls were visible
- Emotes were available
- Chat was available
- The capability panel rendered
- Browser baseline checks passed
- WebXR fallback messaging appeared
- The browser experience remained available without immersive WebXR
The following items remain unverified or incomplete:
- Real-device Android testing
- Real-device iOS testing
- Physical WebXR headset entry and exit
- Controller compatibility
- Long-running realtime reliability
- High-concurrency room testing
- Versioned CDN asset loading
- Manifest rollback
- Full accessibility verification
- Complete LIFE evidence integration
This separation is intentional. A roadmap entry is not evidence that a capability is complete.
Connecting the Metaverse to LIFE
MyZubster is also exploring LIFE-oriented environmental and circular-economy workflows.
The metaverse can provide a public and educational interface for those projects, but it must not replace the underlying evidence system.
The proposed flow is:
Real-world pilot↓
Measurement or observation
↓
Data provenance
↓
Evidence classification
↓
KPI / MRV calculation
↓
MyZubster project record
↓
Metaverse representation
↓
Educational mission
↓
Community feedback
A scene might contain:
- A portal to a pilot
- A visualization of measurements
- A description of the methodology
- A list of missing evidence
- A contribution mission
- Replication instructions
- KPI and MRV status
However:
3D visualization ≠ verified measurement
simulation ≠ field result
self-declaration ≠ independent validation
project goal ≠ achieved environmental impact
These distinctions should be visible in the interface.
Possible Evidence Contract
A future scene object could include an evidence reference:
{
"id": "water-savings-display",
"type": "evidence-panel",
"position": [4, 1.5, -2],
"evidence": {
"status": "measured",
"source": "pilot-observation-2026-10",
"methodologyVersion": "0.2",
"independentVerification": false
}
}
Possible evidence states might include:
planned
self-declared
observed
measured
methodology-reviewed
independently-verified
disputed
superseded
The client could render these states differently without misrepresenting their confidence level.
Remaining Engineering Work
Immutable Manifest History
The current active manifest should eventually become a pointer to an immutable history.
{
roomId: 'room-123',
version: '7',
schemaVersion: '1',
assetBundleVersion: '42',
checksum: 'sha256:...',
manifest: {},
createdBy: 'account-reference',
createdAt: '2026-10-12T00:00:00Z'
}
The structure should become:
VirtualRoom
│
└── activeManifestVersion: 7
SceneManifestVersion
├── version 5
├── version 6
└── version 7
Safe Rollback
Rollback should create a new version based on a previous snapshot:
v5 → v6 → v7
│
└── rollback to v6
↓
v8
Version 7 should not be deleted or overwritten. This preserves auditability.
CDN Asset Pipeline
A future pipeline should follow:
upload
↓
validate
↓
scan
↓
optimize
↓
calculate hash
↓
assign immutable version
↓
publish to CDN
↓
reference from manifest
Asset URLs should be immutable:
/scenes/neon-plaza.42.glb
/textures/neon-floor.18.webp
/audio/neon-ambient.7.ogg
Client-Side Scene Loader
The client will eventually need a structured loading pipeline:
fetch room
↓
fetch active manifest
↓
validate schema version
↓
compare required capabilities
↓
load critical assets
↓
load optional assets
↓
report failures
↓
enter scene
Graceful Asset Failure
Not every asset failure should destroy the whole scene.
critical asset missing
→ load fallback scene
important asset missing
→ continue with visible warning
optional asset missing
→ omit it and continue
A future asset entry could declare this:
{
"id": "neon-plaza",
"type": "glb",
"url": "https://cdn.myzubster.com/scenes/neon-plaza.42.glb",
"criticality": "critical",
"fallbackAssetId": "basic-plaza"
}
Runtime Resource Budgets
Valid JSON does not guarantee safe runtime performance.
We still need budgets for:
- File size
- Polygon count
- Texture dimensions
- Texture memory
- Draw calls
- Animation count
- Shader complexity
- Audio duration
- Video resolution
- Concurrent requests
- Scene initialization time
Mobile Validation
A real-device test matrix should include:
- Android Chrome
- Android Firefox
- iOS Safari
- iPadOS Safari
- Low-memory devices
- Slow networks
- Small screens
- Touch-only interaction
- Screen rotation
- Background and resume behavior
WebXR Device Validation
Physical-headset testing should cover:
- Entering immersive mode
- Exiting immersive mode
- Session interruption
- Controller input
- Focus loss
- Boundary changes
- Sleep and resume
- Spatial audio
- Motion comfort
- Performance degradation
Realtime Reliability
Load tests should cover:
- Concurrent joins
- Concurrent leaves
- Chat bursts
- Stage requests
- Moderation operations
- Reconnect storms
- Token refresh
- Database latency
- Redis degradation
- Server restart
- Network partitions
Accessibility
Browser-first also means accessible-first.
The remaining accessibility work includes:
- Keyboard navigation
- Screen-reader semantics
- Focus management
- Reduced motion
- Colour contrast
- Text scaling
- Captions
- Touch-target sizing
- Non-spatial alternatives
- Cognitive-load review
Important project information must never be available only through an immersive 3D interaction.
Proposed Roadmap
C2.1 — Immutable Manifest Versions
create version model
→ validate manifest
→ calculate checksum
→ store immutable snapshot
→ update active pointer
C2.2 — Rollback
select previous version
→ validate snapshot
→ create a new version
→ update active pointer
→ preserve audit history
C2.3 — Asset Pipeline
upload
→ validate
→ optimize
→ hash
→ version
→ publish
→ reference
C2.4 — Client Scene Loader
fetch
→ validate
→ negotiate capabilities
→ load
→ apply fallbacks
→ expose status
C2.5 — First LIFE Scene
select pilot
→ define evidence contract
→ define KPI/MRV boundaries
→ generate manifest
→ implement scene
→ run public test
How to Contribute
The most useful contributions currently include:
- Mobile browser test reports
- Real-headset WebXR test reports
- Scene-manifest reviews
- glTF and GLB validation
- Asset optimization
- Accessibility testing
- Realtime load tests
- Security reviews
- CDN design
- Rollback implementation
- LIFE evidence modelling
- KPI/MRV data contracts
- Technical documentation
A useful test report should contain:
device
operating system
browser
exact version
network conditions
steps performed
expected result
observed result
logs or screenshots when safe
related issue or pull request
Do not include:
- Passwords
- Authentication tokens
- Private keys
- Wallet seed phrases
- Unredacted personal information
- Sensitive participant details
- Precise private locations
Conclusion
The MyZubster Metaverse now has two important engineering foundations:
- A browser-first capability layer where WebXR is progressive enhancement
- A server-validated scene contract that blocks invalid manifests from publication
The completed work is publicly traceable:
- PR #1597 — Browser and WebXR fallback
- PR #1601 — Versioned scene-manifest validation
The next phase is not simply about adding more 3D content.
It is about creating a reliable technical chain:
code
→ validated contract
→ immutable version
→ versioned asset
→ reliable session
→ real-world pilot
→ evidence
→ understandable visualization
→ community contribution
That is the direction of the MyZubster Metaverse: an open, browser-first environment connecting virtual experiences to public code, documented projects, explicit evidence boundaries, and real-world collaboration.
Status verified: October 12, 2026.
15:21