Qortal-Nextcloud-Integration/docs/future-plans/NuQloud-world/nuqloud-world-next-gen-interface-implementation-plan.md

# NuQloud World Next-Generation Interface Implementation Plan

## Purpose

Build NuQloud World as an optional, plugin-delivered theme/interface layer for
NuQloud for Nextcloud. The goal is a living cloud command environment that
adds spatial navigation, motion, service status, and QDN publishing workflows
on top of NuQloud-native surfaces.

NuQloud World must be built as a theme-grade Nextcloud app/plugin wherever
possible. It must not require a maintained Nextcloud fork, and it must not
become a second dashboard product.

## Source Inputs

This plan is based on:

- The NuQloud World Interface build and rollout plan.
- Concept screenshots in `docs/future-plans/NuQloud-world/Concept-Screenshots/Interface-ReBrand-Concept-1/`.
- Website and architecture concepts in `docs/future-plans/NuQloud-world/Concept-Screenshots/NuQloud-Website-Concept/`.
- Current app and plugin boundary notes in `docs/plugin-roadmap.md`.
- Product mode guidance in `docs/nuqloud-blueprint.md`.

## Dependency Note

Phaser 4 is now a viable planning target, but the implementation should pin an
exact version during Phase 0.

Official references checked while preparing this plan:

- Phaser 4 overview: `https://phaser.io/phaser4`
- Stable Phaser download page: `https://phaser.io/download/stable`
- Phaser GitHub releases: `https://github.com/phaserjs/phaser/releases`

As of July 6, 2026, Phaser's stable download page lists Phaser `v4.2.0`
released on June 19, 2026. Do not depend on unpinned `latest` packages.

## Product Positioning

NuQloud World is not a game. It is a spatial cloud interface for:

- Files and protected storage.
- Private communication.
- Deck tasks and projects.
- QDN publishing.
- Instance health and operational status.
- Account and identity state.

The existing NuQloud surfaces remain the productivity layer. World Mode is the
optional "wow layer" and should feel like a deep theme over the same product,
not a separate dashboard users must learn from scratch.

## Theme-Grade Plugin Architecture

### Recommended App Shape

Create a new Nextcloud app that behaves as a NuQloud theme/interface shell:

```text
nuqloud_world/
+-- appinfo/
|   +-- info.xml
|   +-- routes.php
+-- lib/
|   +-- AppInfo/Application.php
|   +-- Controller/PageController.php
|   +-- Controller/Api/WorldStateController.php
|   +-- Controller/Api/PublishController.php
|   +-- Service/WorldStateService.php
|   +-- Service/FeatureFlagService.php
|   +-- Service/Integration/
|   |   +-- CoreIntegration.php
|   |   +-- FilesBridgeIntegration.php
|   |   +-- TalkBridgeIntegration.php
|   |   +-- QdnIntegration.php
|   +-- Db/
|       +-- WorldPreferenceMapper.php
|       +-- WorldPreference.php
+-- src/
|   +-- main.tsx
|   +-- app/
|   +-- phaser/
|   +-- ui/
|   +-- api/
|   +-- state/
|   +-- events/
|   +-- theme/
|   +-- i18n/
|   +-- types/
+-- templates/
|   +-- world.php
+-- img/
+-- css/
+-- package.json
```

### Integration Boundaries

The theme/interface plugin should depend on existing app capabilities instead
of duplicating them:

- `qortal_integration`: account state, identity state, feature flags, QDN API
  gateway configuration, product language mode.
- `qortal_files_bridge`: file publish state, protected folder state, QDN file
  publish actions.
- `qortal_talk_bridge`: conversation summary, unread counts, relay state.
- NuQloud Deck surface: task/project summaries.
- `custom_pwa`: future install/deep-link affordances only.

CHD admin tooling must remain internal-only and must not be exposed through
NuQloud World.

Q-Deck is the QDN-native app and is out of scope for this NuQloud-native
interface plan. Cross-collaboration between NuQloud Deck and Q-Deck should be
handled by a separate future plugin.

## Runtime Model

```text
Authenticated user
-> /apps/nuqloud_world/world
-> Nextcloud controller renders shell
-> compiled React + Phaser bundle loads
-> client requests /apps/nuqloud_world/api/state
-> server aggregates allowed state from installed apps
-> Phaser renders world state
-> HTML panels perform real actions
```

Phaser owns visual interaction only:

- Background scene.
- Spatial service map.
- Hover and focus effects.
- Activity pulses.
- Service status visualization.
- QDN portal animation.
- Optional drag/drop affordances.

HTML/React owns productive work:

- File lists.
- Forms.
- Publish confirmation.
- Message previews.
- Task details.
- Admin status.
- Settings.
- Accessibility fallback controls.

Rule: Phaser emits intent; the app executes business logic.

## Routes

Authenticated routes:

```text
GET  /apps/nuqloud_world/world
GET  /apps/nuqloud_world/settings
GET  /apps/nuqloud_world/api/state
GET  /apps/nuqloud_world/api/services
GET  /apps/nuqloud_world/api/activity
POST /apps/nuqloud_world/api/preferences
POST /apps/nuqloud_world/api/publish/prepare
POST /apps/nuqloud_world/api/publish/confirm
```

No public endpoints are required for MVP.

If a later public marketing preview is needed, it must be a separate static
route with no user, file, identity, health, or service data.

## Interface Modes

### Existing NuQloud Surface

Purpose:

- Fast productivity.
- Full accessibility.
- Admin and heavy work.
- Default for existing users.

Implementation:

- Use the existing NuQloud/Nextcloud routes and surfaces.
- Do not create a competing dashboard route.
- NuQloud World may link back to these surfaces or open focused panels over
  them.

### NuQloud World

Purpose:

- Branded spatial interface.
- Live service status.
- Contextual command panels.
- Optional immersive mode.

Route:

```text
/apps/nuqloud_world/world
```

### Compact Mobile

Purpose:

- Touch-first mobile use.
- Minimal animation.
- Fast loading.
- Optional or disabled Phaser scene.

Implementation:

- Same route as World Mode.
- Client selects compact shell based on viewport, user preference, reduced
  motion, and performance signals.

## Visual Direction From Concepts

The screenshots establish the visual target:

- Dark command-shell foundation.
- Left-side navigation with clear active state.
- Dense but calm command content.
- Glassy panels with subtle borders.
- Blue primary actions.
- Green healthy/online signals.
- Purple or cyan for publishing/network highlights.
- Gold only for credit/plan emphasis.
- Large data visualization surfaces where useful.
- Side detail panels for Files, Talk, and status.
- Enterprise-grade language and layout discipline.

NuQloud World should reinterpret these as a spatial command layer:

- The concept globe/network becomes the central world backdrop.
- Files become a vault/storage island.
- Talk/private mail becomes a conversation sphere.
- Publishing/redundancy becomes a QDN portal and node map.
- Admin/status becomes an operations core.
- Cards become HTML overlay panels, not Phaser text-only UI.

Avoid:

- Cartoon game assets.
- RPG-style characters.
- Fake metaverse language.
- Canvas-only forms.
- Heavy 3D dependencies for MVP.
- One-off hardcoded colors instead of theme variables.

## Product Language Modes

Default mode is Powered Mode.

Powered Mode language:

- Use `NuQloud`.
- Use `QDN` where protocol specificity is needed.
- Use `Powered by Qortal` where attribution is needed.
- Use `credits` for publishing capacity.
- Avoid wallet, coins, and QORT terminology.

Full Qortal Mode language:

- Crypto-native terminology is allowed.
- Qortal-specific labels may be shown.

Implementation rules:

- Never mix modes in the same view.
- All UI labels must come from translatable strings.
- Product mode must be read from server-side app config.
- Client-side mode is display-only and must not be trusted for authorization.

## MVP World Layout

Initial service map:

```text
                         QDN Portal

                             |

Talk / Private Mail -- NuQloud Core -- Files Vault

                             |

                          Deck Board

                             |

                       Admin / Status
```

MVP service nodes:

- NuQloud Core.
- Files Vault.
- Talk or Private Mail.
- Deck Board.
- QDN Portal.
- Admin / Status.

Each node needs:

- Stable `id`.
- Translated label.
- Translated description.
- Status.
- Badge count.
- Position.
- Icon or sprite key.
- Hover state.
- Click action.
- Activity pulse.
- HTML fallback action.

Example model:

```ts
type WorldServiceNode = {
  id: 'core' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin';
  labelKey: string;
  descriptionKey: string;
  status: 'healthy' | 'warning' | 'error' | 'unknown';
  badgeCount?: number;
  position: {
    x: number;
    y: number;
  };
  panel: 'overview' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin';
  requiredCapability?: string;
};
```

## Panel Scope

Panels must be HTML/React components, not Phaser UI.

### Overview Panel

MVP content:

- Instance name.
- Account display label.
- Overall health.
- Storage summary.
- Active apps summary.
- Recent activity.
- Current mode and World preference.

### Files Panel

MVP content:

- Storage usage.
- Protected folder count.
- Recent files.
- Recent publish states if Files Bridge is installed.
- Open full Files link.
- Publish selected file action where authorized.

### Talk Panel

MVP content:

- Unread count.
- Recent conversations.
- Relay or bridge state if Talk Bridge is installed.
- Open full Talk link.
- Message preview placeholder with no raw rendered user HTML.

### Deck Panel

MVP content:

- Active tasks count.
- Recent tasks.
- Project links.
- Open full Deck link.
- Graceful unavailable state if the Deck surface is absent.

### QDN Publish Panel

MVP content:

- Publish target.
- Selected file placeholder.
- Service/name/identifier fields.
- Server-side validation messages.
- Confirmation step.
- Pending/success/failure state.
- Receipt summary.

### Admin / Status Panel

MVP content:

- Nextcloud status.
- QDN gateway status.
- Qortal node status where allowed by product mode and permissions.
- Talk backend status.
- Office backend status where configured.
- Redis status.
- Database status.
- Storage status.

Admin-only data must be withheld from non-admin users.

## Event Architecture

Use a typed event bus between Phaser, React state, and API updates.

Event rule:

- Phaser sends UI intent.
- React/store sends state changes.
- API services execute actions.
- Phaser reacts visually to approved state.

Core events:

```text
ui.openPanel
ui.closePanel
ui.focusService
ui.clearFocus
ui.setMode

service.statusChanged
service.badgeChanged
service.activityPulse
service.capabilityUnavailable

files.fileSelected
files.filePublished

talk.messageReceived
deck.taskUpdated

qdn.publishPrepared
qdn.publishStarted
qdn.publishCompleted
qdn.publishFailed

admin.healthChanged
preferences.updated
```

Example:

```ts
type WorldEvent =
  | {
      type: 'ui.openPanel';
      panel: 'overview' | 'files' | 'talk' | 'deck' | 'qdn' | 'admin' | 'settings';
      context?: Record<string, unknown>;
    }
  | {
      type: 'service.statusChanged';
      serviceId: WorldServiceNode['id'];
      status: 'healthy' | 'warning' | 'error' | 'unknown';
    }
  | {
      type: 'qdn.publishCompleted';
      publishId: string;
      receiptUrl?: string;
    };
```

## State Shape

```ts
type WorldState = {
  mode: 'existing' | 'world' | 'compact';
  productMode: 'powered' | 'full_qortal';
  user: {
    id: string;
    displayName: string;
    isAdmin: boolean;
  };
  instance: {
    name: string;
    baseUrl: string;
    status: 'healthy' | 'warning' | 'error' | 'unknown';
  };
  capabilities: Record<string, boolean>;
  services: WorldServiceNode[];
  badges: Record<string, number>;
  activity: WorldActivityItem[];
  preferences: {
    worldModeEnabled: boolean;
    reducedMotion: boolean;
    compactMode: boolean;
  };
};
```

## Data Integration

Phase 1 uses fixtures only.

Phase 2 adds aggregated server state:

- Current user.
- Instance name.
- Storage used and quota.
- Recent files.
- Protected folders.
- Talk unread count.
- Recent conversations.
- Active Deck task count.
- Pending QDN publishes.
- Basic service health.
- Recent activity feed.

MVP update strategy:

- Poll service status every 30 to 60 seconds.
- Poll message/Deck task badges every 10 to 30 seconds.
- Poll storage every 60 to 300 seconds.
- Poll active publish jobs every 5 to 15 seconds.
- Add SSE or WebSocket only after the data model is stable.

## Security Requirements

Mandatory rules:

- All product routes authenticated by default.
- All mutating API routes require CSRF protection.
- All publish actions require server-side authorization.
- All input must be validated and sanitized server-side.
- Do not trust node id, service id, file id, path, product mode, or permissions
  supplied by the client.
- Do not expose secrets, broker tokens, private node credentials, or internal
  service URLs to the browser.
- Do not render raw user input in panels, tooltips, activity feeds, or Phaser
  labels.
- Return capability-limited state for non-admin users.
- Define public endpoints separately before adding any.

QDN publish flow:

```text
Client selects file
-> server verifies file access
-> server prepares publish request
-> user confirms in HTML panel
-> server submits publish action
-> server returns sanitized status/receipt
-> Phaser animates pending/success/failure
```

## Accessibility Requirements

NuQloud World cannot be canvas-only.

Required:

- Every primary Phaser action also exists as an HTML button or navigation item.
- Keyboard navigation for service nodes and panels.
- ARIA labels on panels, dialogs, command controls, and status indicators.
- Focus trap for modal or side-panel workflows.
- Escape closes active panel.
- Reduced-motion preference.
- Compact/mobile fallback.
- Visible focus states using theme variables.
- No essential text rendered only inside Phaser.

## Theming Requirements

Use Nextcloud and NuQloud theme variables:

- No hardcoded UI colors in components unless they are token definitions.
- Support dark first, with light mode compatibility later.
- Preserve concept accent roles:
  - blue for primary actions and selected navigation.
  - green for healthy/online/synced.
  - purple/cyan for publishing/network activity.
  - gold for credits or plan emphasis only.
- Keep panels responsive and mobile-first.
- Avoid nested card-heavy layouts in World overlays.

## Performance Requirements

MVP targets:

- World route should feel immediate after auth.
- Mobile should default to compact or simplified mode.
- Idle CPU must stay low.
- Particle count must be capped.
- World assets must lazy-load.
- Animations pause or reduce when the tab is inactive.
- Reduced-motion mode disables non-essential animation.
- Texture assets should be optimized and bundled predictably.
- Avoid custom shaders in MVP unless a fallback exists.

## Build Strategy

Recommended frontend:

- TypeScript.
- React.
- Phaser 4.
- Lightweight store such as Zustand or equivalent.
- Typed event bus.
- CSS tokens.

Recommended packaging:

- Build compiled assets into the Nextcloud app's `js/` and `css/` output.
- Keep the app loadable through normal Nextcloud script/style registration.
- Use Vite if it can emit Nextcloud-compatible static assets cleanly.
- Otherwise follow the repository's current app asset pipeline.

Do not require a standalone NuQloud frontend server for production.

## Feature Flags

Server-side flags:

```ts
type NuQloudWorldFlags = {
  worldModeEnabled: boolean;
  worldModeDefault: boolean;
  worldModeBetaBadge: boolean;
  qdnPortalEnabled: boolean;
  deckNodeEnabled: boolean;
  talkNodeEnabled: boolean;
  filesNodeEnabled: boolean;
  adminStatusNodeEnabled: boolean;
  liveActivityEnabled: boolean;
  reducedMotionDefault: boolean;
};
```

Defaults:

- `worldModeEnabled`: false until beta.
- `worldModeDefault`: false until proven.
- `qdnPortalEnabled`: true only when integration is available.
- `adminStatusNodeEnabled`: visible to admins, limited for users.
- `reducedMotionDefault`: follow user/system preference.

## Rollout Phases

### Phase 0 - Design and Technical Lock

Deliverables:

- Confirm plugin app id.
- Confirm supported Nextcloud versions.
- Pin Phaser 4 version.
- Define service node list.
- Define panel list.
- Define event schema.
- Define API state contract.
- Define route map.
- Define theme tokens.
- Define feature flags.
- Define MVP acceptance criteria.
- Confirm language mode dictionary.

Exit criteria:

- No ambiguity about Phaser vs HTML responsibilities.
- No ambiguity about app/plugin boundaries.
- Implementation tickets can be created from this plan.

### Phase 1 - Static Plugin Prototype

Build:

- New Nextcloud app shell.
- Authenticated `/world` route.
- Compiled TypeScript frontend bundle.
- Phaser boot scene.
- Static WorldScene.
- Five to six service nodes.
- Hover/focus/click effects.
- HTML overlay panel host.
- Mock panel content.
- Mock status badges.
- Reduced-motion toggle.

Exit criteria:

- `/apps/nuqloud_world/world` loads for authenticated users.
- Unauthenticated users cannot access it.
- Service nodes render.
- Hover, keyboard focus, and click open panels.
- Panels can open and close.
- No real publish action exists yet.

### Phase 2 - State and Event Bus

Build:

- Typed event bus.
- World state store.
- Panel store.
- Service status store.
- Preference store.
- Mock activity events.
- Phaser subscriptions to store updates.
- HTML command bar fallback.

Exit criteria:

- Phaser does not own business logic.
- State updates affect both panels and scene objects.
- All primary actions work without clicking the canvas.
- Mock activity pulses work.

### Phase 3 - Aggregated Server State

Build:

- `WorldStateController`.
- `WorldStateService`.
- Integration services for installed NuQloud apps.
- Capability detection.
- Sanitized JSON state endpoint.
- Loading/error/offline states.
- Basic polling.

Exit criteria:

- Real counts show where integrations are installed.
- Missing integrations degrade gracefully.
- Non-admin users do not receive admin-only data.
- API errors render cleanly.

### Phase 4 - QDN Portal MVP

Build:

- Select file from Files panel.
- Prepare publish request server-side.
- Confirmation panel.
- Submit publish action server-side.
- Pending state.
- Success/failure receipt.
- Phaser portal animations based on approved server state.

Exit criteria:

- No destructive or publishing action happens without confirmation.
- Invalid file ids, paths, names, services, and identifiers are rejected.
- Publish status is visible in both panel and world node.
- Errors expose no secrets.

### Phase 5 - Useful Spatial Workflows

Build one workflow that makes the theme layer useful beyond visual polish:

- Conversation/project room.
- Linked files.
- Linked Deck tasks.
- QDN publish history.
- Activity timeline.
- Open object -> real panel/detail view.

Exit criteria:

- A user can move from conversation/project context to files/Deck/publishing
  without losing context.
- Spatial view is not decorative only.

### Phase 6 - Mobile and Accessibility Hardening

Build:

- Compact shell.
- Touch-safe controls.
- Keyboard navigation pass.
- ARIA audit.
- Reduced-motion pass.
- Performance budget pass.
- Cross-browser sanity pass.

Exit criteria:

- Mobile users are not forced into heavy world mode.
- All core actions work without Phaser.
- Focus order is understandable.
- Reduced motion meaningfully reduces animation.

### Phase 7 - Private Beta

Rollout:

- Enable behind feature flag.
- Default users to existing NuQloud surfaces.
- Allow opt-in to World Mode.
- Collect feedback.
- Track performance and usage.

Metrics:

- World Mode activation rate.
- Repeat usage.
- Time to first useful action.
- Panel open counts.
- Publish completion rate.
- API failure rate.
- Slow load rate.
- Mobile fallback usage.

Exit criteria:

- Users understand the interface.
- Performance is acceptable.
- No major accessibility blocker remains.
- World Mode creates clear product differentiation.

### Phase 8 - Public Launch Readiness

Build:

- Final branded art assets.
- Polished animations.
- Preference setting.
- Admin controls.
- Documentation.
- Marketing screenshots/video.
- Upgrade notes.

Exit criteria:

- App can ship without a Nextcloud fork.
- Feature flags support rollback.
- Admins can disable World Mode.
- Documentation explains existing, world, and compact modes.

## Implementation Tickets

### Foundation

- Create `nuqloud_world` app scaffold.
- Add authenticated page controller.
- Add route registration.
- Add frontend build pipeline.
- Add feature flag service.
- Add world preference storage.

### Frontend Shell

- Add React app shell.
- Add Phaser game mount/unmount lifecycle.
- Add overlay layer.
- Add panel host.
- Add command bar.
- Add compact shell.
- Add theme token file.
- Add i18n files.

### Phaser Layer

- Add BootScene.
- Add PreloadScene.
- Add WorldScene.
- Add EffectsScene.
- Add ServiceNode object.
- Add FilesVault object.
- Add TalkSphere object.
- Add DeckBoard object.
- Add QdnPortal object.
- Add AdminCore object.
- Add reduced-motion behavior.

### State and Events

- Add typed world event definitions.
- Add world bus.
- Add world store.
- Add service status store.
- Add panel store.
- Add preference store.
- Add mock event generator for prototype only.

### API and Services

- Add state endpoint.
- Add service capability endpoint.
- Add activity endpoint.
- Add preferences endpoint.
- Add publish prepare endpoint.
- Add publish confirm endpoint.
- Add integration adapters for core, Files Bridge, Talk Bridge, and QDN.

### Panels

- Add Overview panel.
- Add Files panel.
- Add Talk panel.
- Add Deck panel.
- Add QDN Publish panel.
- Add Admin Status panel.
- Add Settings panel.
- Add unavailable integration state.

### Security

- Add CSRF coverage for mutating endpoints.
- Add server-side authorization checks.
- Add input validation helpers.
- Add output sanitization policy.
- Add permission-limited state shaping.
- Add admin-only status filtering.

### Accessibility

- Add keyboard node navigation.
- Add HTML action equivalents.
- Add ARIA labels and roles.
- Add focus management.
- Add reduced-motion toggle.
- Add compact fallback.

### QA and Release

- Add unit tests for services and validation.
- Add frontend tests for event/store behavior.
- Add route/auth tests.
- Add manual devcloud verification steps.
- Add beta flag rollout docs.
- Add rollback docs.

## Acceptance Criteria

MVP is complete when:

- World Mode is delivered as a theme-grade Nextcloud app/plugin.
- No Nextcloud fork is required.
- Route is authenticated.
- All mutating actions are CSRF protected.
- No raw user input is rendered.
- Service nodes and HTML fallback actions match.
- Panels use translated strings.
- Product language mode is consistent per view.
- Core state loads from a server endpoint.
- Missing integrations degrade gracefully.
- QDN publish workflow requires confirmation.
- Reduced-motion and compact modes exist.
- Admin-only state is not exposed to regular users.

## Devcloud Verification Commands

Use devcloud only. Do not run local Docker/Nextcloud for this work.

Example commands once implementation begins:

```bash
docker compose --env-file .env.devcloud exec nextcloud php occ app:list
docker compose --env-file .env.devcloud exec nextcloud php occ app:enable nuqloud_world
docker compose --env-file .env.devcloud exec nextcloud php occ app:check-code nuqloud_world
docker compose --env-file .env.devcloud exec nextcloud php occ config:app:get nuqloud_world worldModeEnabled
docker compose --env-file .env.devcloud exec nextcloud php occ maintenance:repair --include-expensive
```

Frontend build verification, from the app directory:

```bash
npm ci
npm run build
npm test -- --run
```

## Verify-by-Inspection Checklist

- App structure valid: `appinfo/`, `routes.php`, controllers, services.
- Auth enforced on all product routes.
- Public endpoints explicitly absent or separately documented.
- CSRF enforced on all mutating endpoints.
- No raw user input rendered.
- No secrets exposed to logs or client state.
- Imports and exports consistent.
- i18n used for UI labels.
- Theme variables used instead of hardcoded component colors.
- Product language mode not mixed in a view.
- CHD admin surfaces not exposed.
- Nextcloud version compatibility checked in Phase 0.
- Mobile and reduced-motion fallbacks included.