Cloud Phone Types

Cloud Phone TypeScript type declarations.

Installation

NPM

npm install -D @cloudmosa-inc/cloudphone-types

PNPM

pnpm add @cloudmosa-inc/cloudphone-types --save-dev

Bun

bun add --development @cloudmosa-inc/cloudphone-types

Cloud Phone APIs

This document provides a reference for all non-standard APIs specific to Cloud Phone. These are custom APIs that extend standard web APIs to support Cloud Phone's unique features and hardware constraints.

Table of Contents

• Feature Detection API
• Volume Manager API
• Back Event Handler
• Custom HTML Attributes

Feature Detection API

The Feature Detection API allows you to detect specific Cloud Phone client capabilities so your app can offer the best user experience.

Signature

navigator.hasFeature(name: string): Promise<boolean>

Availability

• Available on main thread and Web Workers
• Available on all Cloud Phone client versions
• Feature names are case-sensitive

Supported Features

| Feature | Description | | ------------------- | ------------------------------------------------------------------------ | | AudioCapture | Audio recording using getUserMedia is supported | | AudioPlay | Audio playback is supported for HTMLAudioElement | | AudioSeek | Audio seeking is supported via HTMLMediaElement.currentTime | | AudioUpload | Audio uploads are supported using <input type="file" accept="audio/*"> | | VideoCapture | Video recording using getUserMedia is supported | | VideoSeek | Video seeking is supported via HTMLMediaElement.currentTime | | VideoUpload | Video uploads are supported using <input type="file" accept="video/*"> | | EmbeddedTextInput | Embedded text input (IME with header/footer) is supported | | FileDownload | File downloads are supported using <a download> | | FileUpload | File uploads are supported using <input type="file"> | | ImageUpload | Image uploads are supported using <input type="file" accept="image/*"> | | SmsScheme | Links using sms: URI scheme are supported | | TelScheme | Links using tel: URI scheme are supported | | Vibrate | Vibration hardware is supported via navigator.vibrate() |

Example Usage

// Check if file downloads are supported
const fileDownloadSupported = await navigator.hasFeature("FileDownload");

if (fileDownloadSupported) {
  downloadLink.setAttribute("download", "podcast.mp3");
  downloadLink.classList.remove("hidden");
}

// Check if video seeking is supported
if (await navigator.hasFeature("VideoSeek")) {
  scrubber.classList.remove("hidden");
}

// Check if vibration is supported
if (await navigator.hasFeature("Vibrate")) {
  navigator.vibrate(200); // Vibrate for 200ms
}

Important Notes

• Feature names are case-sensitive
• Invalid feature names resolve to false
• This detects software capabilities, not hardware availability or permissions
• Always catch exceptions when using detected features (e.g., getUserMedia may throw NotAllowedError or NotFoundError)

Documentation - Feature Detection

See Feature Detection for complete documentation.

Volume Manager API

The Volume Manager API allows control of the system volume on Cloud Phone devices. Many Cloud Phone devices lack physical volume rockers, making this API essential for user experience.

Interface

interface VolumeManager {
  requestUp(): void;
  requestDown(): void;
}

Available on navigator.volumeManager (may be undefined on non-Cloud Phone browsers).

Methods

requestUp()

Displays the volume HUD and immediately raises the system volume by one increment.

navigator.volumeManager.requestUp();

requestDown()

Displays the volume HUD and immediately lowers the system volume by one increment.

navigator.volumeManager.requestDown();

Example Usage - Volume Manager

// Bind volume controls to custom keys
document.addEventListener("keydown", (e) => {
  if (e.key === "1" && navigator.volumeManager) {
    navigator.volumeManager.requestUp();
  } else if (e.key === "2" && navigator.volumeManager) {
    navigator.volumeManager.requestDown();
  }
});

Important Notes - Volume Manafger

• Controls system volume, not playback volume
• HTMLMediaElement.volume does not work on Cloud Phone; use volumeManager instead
• Volume HUD appearance varies by device (different styles and increment counts)
• While HUD is visible, arrow keys are intercepted for volume control
• Volume HUD automatically dismisses after a few seconds of inactivity

Documentation - Volume Manager

See Multimedia - Volume Manager API for complete documentation.

Back Event Handler

The Back Event Handler allows you to override the default behavior of the Right Soft Key (RSK), which normally triggers history.back().

Event Signature

window.addEventListener("back", (event: Event) => void);

Description

The global "back" event fires when the user presses the Right Soft Key (RSK). By default, this navigates back in history or exits the app. You can intercept this behavior using event.preventDefault().

Example Usage - Back Event

Basic Override

window.addEventListener("back", (event) => {
  event.preventDefault();
  // Handle custom back behavior
  goToPreviousScreen();
});

Exit Confirmation

window.addEventListener("back", (event) => {
  if (isSomethingToGoBackTo) {
    event.preventDefault();
    // Return to previous page
    goBackInTime();
  } else {
    // Quit widget
    window.close();
  }
});

Conditional Interception

let modalOpen = false;

window.addEventListener("back", (event) => {
  if (modalOpen) {
    event.preventDefault();
    closeModal();
  }
  // If modal is not open, allow default behavior (exit app)
});

Important Notes - Back Event

• RSK is the physical Right Soft Key on Cloud Phone devices
• Default behavior: history.back() or exit app if no history
• Call event.preventDefault() to intercept the default behavior
• Call window.close() to explicitly quit the widget
• If you don't call preventDefault(), the app will exit when history is empty

Documentation - Back Event

See Cloud Phone Design - Soft Keys for complete documentation.

Custom HTML Attributes

Cloud Phone provides custom HTML attributes for controlling specific behaviors.

x-puffin-entersfullscreen

Controls whether text input displays a fullscreen Input Method Editor (IME) dialog.

Values

• "off" - Disables fullscreen IME (uses embedded input)
• Default - Uses fullscreen IME on devices without embedded input support

Usage

<input type="text" x-puffin-entersfullscreen="off" id="customTextInput" />

When to Use

• Creating custom emoji keyboards
• Building custom input interfaces
• Apps that need to maintain visibility of the input element during editing

Example: Custom Emoji Keyboard

<input type="text" x-puffin-entersfullscreen="off" id="emojiInput" />

const emojiMap = new Map([
  ["1", "😀"],
  ["2", "😃"],
  ["3", "😄"],
]);

const input = document.getElementById("emojiInput");

input.addEventListener("keydown", (e) => {
  const emoji = emojiMap.get(e.key);
  if (emoji) {
    input.value += emoji;
  }
});

Important Notes - Embedded Text Input

• Only affects devices that support EmbeddedTextInput feature
• On devices with fullscreen IME, attribute has no effect
• Apps disabling fullscreen IME must manually handle keyboard input
• Check await navigator.hasFeature("EmbeddedTextInput") to detect support

x-puffin-playsinline

Disables the default fullscreen display for <video> elements.

Usage - Inline Playback

HTML Attribute

<video x-puffin-playsinline src="video.mp4" controls></video>

JavaScript Property

const video = document.createElement("video");
video.playsInline = true;

When to Use - Inline Playback

• Short, small videos (GIF-like clips)
• Inline video previews
• Video thumbnails
• Multi-video layouts

Example

<div class="video-grid">
  <video x-puffin-playsinline src="clip1.mp4" autoplay loop muted></video>
  <video x-puffin-playsinline src="clip2.mp4" autoplay loop muted></video>
  <video x-puffin-playsinline src="clip3.mp4" autoplay loop muted></video>
</div>

Important Notes - Inline Playback

• By default, Cloud Phone plays all videos in fullscreen
• Use this attribute for videos that should remain inline
• Particularly useful for short, looping clips or animations
• Does not affect video playback controls or functionality

Documentation - Inline Playback and Embedded Text Input

• Feature Detection - EmbeddedTextInput
• Multimedia - Inline Playback

TypeScript Support

For TypeScript projects, use the companion types.d.ts declaration file to enable type checking and autocompletion for all Cloud Phone APIs.

// Include in your project
/// <reference path="./types.d.ts" />

// Or add to tsconfig.json
{
  "include": ["types.d.ts"]
}

Additional Resources

• Cloud Phone Developer Portal
• Cloud Phone Architecture
• Cloud Phone Design Guide
• Developer Console

License

Apache 2.0