# QNE Invite Trial Browser View Session Doctrine V2

Status: current operational doctrine
Date: 2026-06-12
Layer: Layer B current support doctrine under the main node view-session doctrine
Workspace anchor: qne-node-v00572, qne-view-session-v00519, qne-scene-data-v00501, qne-window-v00500, qne-theme-v00500, qne-ui-components-v00507, qne-scene-renderer-skia-v00546, qne-ui-v00555, qne-android-app-v00515

This doctrine supersedes `QNE_Invite_Trial_Browser_Shadow_Doctrine_V1.md` and
extends `QNE_Main_Node_View_Session_System_Doctrine_V2.md`. It defines how a
Home Node can invite another person to try QuicknEasy before they install their
own Home Node.

## Summary

A Home Node can host a temporary invited user. The invitee may first access that
user system through a browser QNEViewSession, and may also approve a mobile
device that opens mobile-first QNEViewSessions during the trial. The invitee's
activities are recorded in the invitee user persist under the inviter's Home
Node. When the invitee installs their own Home Node, the invitee user persist
can be migrated to the invitee's new Home Node.

The invite system is not just a download link. It is a working hosted QNE trial
with a PA conversation surface that guides the invitee, explains the system, and
later assists migration.

## Invite Flow

The Home Node owner selects Invite from the Home Node UI or from an approved
mobile QNEViewSession. The Home Node creates:

- an invite record
- an invited user UUID
- a hosted user runtime under `QNE/users/<invitee-user-uuid>`
- a browser QNEViewSession for the first remote session
- optional policy allowing the invitee to approve a mobile device and open
  mobile QNEViewSessions during trial
- an invite link and PIN
- optional QR code for accepting the invite

The invite message may be shared by email, native share sheet, copied link, QR
display, or other user-controlled channel.

The invite message should include:

- qne.info download link for users who want to install immediately
- browser trial link for users who want to try first
- PIN or short code
- expiry statement
- plain language instruction to open the link and enter the PIN

## Browser Trial

The invitee can open the trial link in a browser. The browser loads a reviewed
QNE browser adapter. The browser adapter does not run QNENodeSkills. In the
current video-frame path, it does not render QNESceneData directly once the
session is active. It displays frames generated by the node-side QNEViewSession
and returns pointer, keyboard, viewport, and action controls.

The browser trial persists browser/session-specific state only:

- invite ID
- browser view-session ID
- PIN verification state
- scene delivery state
- client capability hints
- expiry and revocation state
- audit events for access attempts

The current persisted invite key is `browser_view_session_id`. Browser
view-session records and state files live under
`persist/browser-view-sessions/`. Older pilot storage using
`browser_shadow_id` and `persist/browser-shadows/` is legacy input only and must
be rewritten with `storage-migrate --qne-home PATH` before production use.

The browser QNEViewSession is not the user system. The invitee's actual
activity belongs in the invitee user persist.

The browser QNEViewSession follows the QNE color doctrine from the main node
view-session doctrine. Browser adapter fallback colors and node-rendered frame
colors must be defined from OKLCH design values and converted to CSS or Skia
output formats only at the adapter edge. The standard Personal Assistant window
title bar is pastel green.

The browser trial view uses standard configured internal window instances. The
base window shell is common; the typed work area inside the shell determines
behavior and content. The initial trial scene contains at least the Personal
Assistant work area and the My Device Guru work area. Closed trial windows are
represented by fixed right-side viewport circles below the toolbar, and
minimized trial windows by fixed left-side viewport circles below the toolbar.
Those circles are node-rendered frame content with browser pointer control
events, not DOM controls. Clicking a visible trial window focuses it and moves
it to the top z-order in the node-rendered frame.

The browser is a dumb full-frame display with a control channel. Browser-side
activity is limited to frame display, resize/visibility handling, pointer/
keyboard/touch/control capture, keepalive where required, and platform hints.
The browser must not contain business logic, QNENodeSkill execution, downloaded
QNE executable behavior, or direct QNESceneData rendering for active
QNEViewSessions.

The node-side QNEViewSession is implemented in the separate
`qne-view-session-vNNNNN` project. Reusable window/panpanel mechanics are
implemented in the separate `qne-window-vNNNNN` project. Theme tokens and
standard controls are implemented in `qne-theme-vNNNNN` and
`qne-ui-components-vNNNNN`. Browser trial behavior changes should update those
projects and the renderer project when possible, not qne-node, unless the node
adapter, invite records, routes, auth, or persistence contract changes.

## Invitee User Persist

The invited user's hosted state lives under the inviter Home Node:

```text
QNE/users/<invitee-user-uuid>/
  persist/
    lmdb/
    ltr/
    secrets/
  status/
    config/
    runtime/
    index/
  tmp/
  ui/
```

Invitee documents, preferences, PA state, trial activity, QNENodeSkill state,
and migration markers belong in this user persist. This layout is intentionally
portable so it can later be copied or transferred to the invitee's own Home
Node.

## Invitee Mobile Device And View Sessions

An invitee may add a mobile device during the hosted trial. The durable mobile
approval record is hosted by the inviter's Home Node but is bound to the
invitee's hosted user, not to the inviter's owner user. Live mobile UI/control
state belongs in QNEViewSessions.

The mobile device record must include enough policy context to prevent confusion:

```text
device_uuid
observed_noise_static_public_key
adapter
device_owner_kind = hosted_trial_user
hosted_user_uuid = <invitee-user-uuid>
invite_id = <invite-id>
approved_by = invite_policy_or_home_node_owner
trial_expires_at
revocation_state
```

The invitee mobile device and its QNEViewSessions can access only the invitee's
hosted user context. They must not gain access to the inviter's owner
user/session. Trial expiry disables browser QNEViewSessions and mobile device
access unless the Home Node owner extends or converts the trial.

When the invitee migrates to their own Home Node, the mobile device should be
paired to the new Home Node. The old hosted mobile device record and related
QNEViewSessions should be revoked, archived, or marked migrated.

## PA-Guided Trial And Migration

Once an invitee is connected through a browser QNEViewSession, mobile
QNEViewSession, local node, or remote node, the invitee's PA is the continuity
and guidance surface.

The PA should guide:

- welcome and orientation
- what the inviter has shared
- privacy and hosting boundaries
- trial expiry
- adding a mobile device
- installing the invitee's own Home Node
- migration from hosted trial to owned Home Node
- known peer/contact setup
- later membership or payment flows where applicable

Migration is a PA-led workflow, not an admin procedure. The PA can detect browser
platform hints and recommend the correct qne.info installer URL, while always
allowing the user to choose another platform.

## Platform Hint Doctrine

Browser platform detection is allowed only as a convenience hint. It may be used
to recommend an installer URL:

```text
Windows -> qne.info Windows installer
macOS -> qne.info macOS installer
Linux -> qne.info Linux installer
Android -> Play Store or Android package path
iOS -> App Store
```

Platform hints must not be used for authorization. They may be derived from user
agent data, browser feature detection, screen/touch hints, and explicit user
choice.

The canonical installer URL mapping should live on the Home Node or qne.info,
not hardcoded permanently in the browser adapter.

## Security Boundaries

An invite link and PIN do not grant broad access. They grant a controlled path
to activate the hosted trial user session.

Invite records should support:

- pending
- accepted
- expired
- revoked
- migrated

Invite links should be short-lived or policy-limited. PIN attempts should be
rate-limited. Browser QNEViewSessions, mobile QNEViewSessions, and approved
mobile device records must be scoped to the invitee user and invite policy.

The invitee's future Home Node owns its own node UUID and QNE P2P static key.
Migration updates the user's current Home Node relationship rather than making
the inviter's Home Node permanent.

## QR And Share Doctrine

Invite QR codes are bootstrap artifacts. They may be displayed on the Home Node
UI, displayed on an approved mobile QNEViewSession, embedded in an email, or
shared through a native share sheet.

The QR payload for an invite should be separate from Home Node mobile pairing
payloads. A QNE invite QR identifies the invite endpoint, invite ID/nonce,
network, expiry, and optional qne.info download link. It does not authorize the
scanner to access private content by itself.

Native share sheets are preferred on mobile because they let the user choose
Mail, Messages, WhatsApp, Signal, AirDrop, or another installed channel without
QNE needing email-provider credentials.

## Migration Doctrine

When the invitee installs their own Home Node:

1. The new Home Node creates its own node UUID and static QNE P2P key.
2. The hosted invitee PA confirms the migration intent.
3. The inviter Home Node authorizes export of the invitee user persist.
4. The user persist bundle is transferred to the invitee Home Node.
5. The invitee Home Node imports it under the same invitee user UUID.
6. Public user/DHT records are updated to point to the new Home Node where
   appropriate.
7. The inviter Home Node marks the hosted user, approved device records, and
   QNEViewSessions as migrated, read-only, revoked, or archived according to
   policy.

The browser/mobile trial path exists to let a person experience QNE before they
commit to running their own Home Node.
