iCanText App Bridge

1. What is an iCanText Micro-App?

A Micro-App is a lightweight, pure-frontend web application (HTML, CSS, JS) that runs directly inside the iCanText user interface. It is not a backend bot, a server-side plugin, or a webhook service.

Instead, it lives in a secure, sandboxed iframe and uses the iCanText App Bridge to turn the P2P mesh network into a decentralized, serverless back-end. Whether you are building a multiplayer game, a collaborative whiteboard, or a secure voting system, the app relies entirely on the users' devices to process and synchronize data.

The Design Framework: Plan Before You Code

Before writing code (or prompting an AI), structure your app by answering three fundamental questions:

// 1. When a new peer opens the app, they request the state
sdk.sendData(peerIds, { type: 'sync_request' });

// 2. Existing peers listen for requests and share their RAM state
sdk.onData((fromId, payload) => {
if (payload.type === 'sync_request') {
    sdk.sendData([fromId], { 
        type: 'sync_response', 
        data: myLocalRamState 
    });
}
if (payload.type === 'sync_response' && !amISyncedYet) {
    myLocalRamState = payload.data;
    amISyncedYet = true;
    renderUI();
}
});

How it works

The iCanText App Bridge is a versatile integration engine that turns iCanText into a Decentralized Operating System. It allows third-party web applications to run seamlessly within the communication flow, leveraging the P2P network as a secure, serverless back-end.

Interaction & Collaboration Models

• Owner Only: (Default) The message context is a private state. Only the original author can update it using updateAppContext.
• Collaborative: The app context is open. Any authorized channel member can perform edits. Ideal for shared settings or simple "last-writer-wins" states.
• Event Sourcing: Instead of overwriting a single state, users emit individual signed App Events. All peers store these in a Universal Ledger, allowing apps to reconstruct perfect state even with high concurrency (e.g. Polls, Games).

Integration Modes

• Channel Header: Install utility apps (like Video Tools or Dashboards) directly in the channel's top bar for quick access by all members.
• Interactive Messages: Post dynamic content (like Polls, Tasks, or Games) that renders as an iframe inside the chat. Use the P2P mesh to sync their state in real-time.
• External Popups: Launch full-scale applications in separate tabs while maintaining a secure link to the user's decentralized identity.

Choosing the Right Communication Flow

The SDK offers three distinct ways to exchange data. Choose based on your persistence requirements:

// 1. When a new peer opens the app, they request the state
			sdk.sendData(peerIds, { type: 'sync_request' });

			// 2. Existing peers listen for requests and share their RAM state
			sdk.onData((fromId, payload) => {
			    if (payload.type === 'sync_request') {
				sdk.sendData([fromId], { 
				    type: 'sync_response', 
				    data: myLocalRamState 
				});
			    }
			    if (payload.type === 'sync_response' && !amISyncedYet) {
				myLocalRamState = payload.data;
				amISyncedYet = true;
				renderUI();
			    }
			});

Understanding interactionModel

The interactionModel option in postAppContent defines who has the right to modify the original message instance itself:

• OWNER_ONLY: Only the author can call updateAppContext. Other members can still contribute via emitAppEvent. This is the safest mode for Polls.
• COLLABORATIVE: Any member with write access to the channel can call updateAppContext to overwrite the shared state.

App Architecture & UI Guidelines

To ensure your micro-app works flawlessly across all iCanText clients and is strictly secure, you must adhere to the following architectural rules:

1. Zero Dependency & Asset Paths

Your application is rendered inside a strict iframe. It does not inherit any CSS or scripts from the iCanText parent.

• Styling: Use inline <style> tags or import from a reliable CDN.
• Assets (Images/Fonts): Because the app runs with an opaque origin (null), relative paths (e.g., ./image.png) will fail. You must use absolute HTTPS URLs, inline SVGs, or Base64 encoded images.

2. Strict Sandbox Constraints (No LocalStorage)

To protect user privacy, micro-apps are sandboxed without the allow-same-origin directive.

• ❌ localStorage, sessionStorage, and IndexedDB will throw security errors or be wiped immediately.
• ✅ Solution: Keep your state in RAM (variables) and rely on the iCanText SDK (updateAppContext or emitAppEvent) for persistence across reloads.

3. Visual Routing via Display Modes

A single HTML file acts as the configuration screen, the chat widget, and the standalone app. Use sdk.getDisplayMode() and connection.status to conditionally hide/show HTML containers:

const connection = await sdk.init();

if (connection.status === 'STANDALONE') {
    // 1. User opened the app URL directly in a browser
    document.getElementById('standalone-config-ui').style.display = 'block';
} else if (sdk.getDisplayMode() === 'MESSAGE') {
    // 2. App is embedded inside the chat timeline
    document.getElementById('chat-interactive-ui').style.display = 'block';
    // Fetch the state specific to this message bubble
    const state = await sdk.getAppContext(); 
} else {
    // 3. App is in HEADER or POPUP mode (usually for config or tools)
    document.getElementById('full-tool-ui').style.display = 'block';
}

4. The "Local Echo" Trap (Event Sourcing)

When you call sdk.emitAppEvent(payload), iCanText immediately processes the event locally and triggers your onAppEvent callback for the sender too. This ensures perfect UI synchronization.

5. Responsive Design for Chat Bubbles

When your app runs in MESSAGE mode, it is displayed inside a chat timeline. It could be viewed on a large desktop monitor or a narrow mobile screen.

• Never hardcode fixed widths (e.g., avoid width: 800px;).
• Use width: 100%; max-width: 800px; box-sizing: border-box;.
• Ensure touch interactions (drag & drop, canvas drawing) handle e.preventDefault() properly so they don't trigger browser scrolling.

Unified Security Handshake

Whether your app is running as a header icon, a chat widget, or an external window, it must perform a rigorous handshake to establish a secure link with iCanText:

1. Initiation: The app is rendered by iCanText. This happens when:
   • A member clicks a Header Icon.
   • An Interactive Message appears in the chat timeline.
   • A user manually types /app https://your-app.com.
2. Hello: Your application script starts and automatically sends an ICT_HELLO signal via postMessage to the parent window.
3. Verification: iCanText identifies the source window, verifies it against its internal registry, and retrieves its specific context (active workspace, permissions).
4. Init: iCanText returns an ICT_INIT payload containing the instanceId, the user's localPeerId, localPseudonym, and its Display Mode.
5. Ready: The bridge is now READY. All subsequent P2P operations are cryptographically locked to this specific app instance.

ICTBridgeSDK.js

We provide a lightweight, promise-based SDK to handle the complexity of postMessage communication and handshaking.

Include it in your HTML:

<script src="https://icantext.com/ICTBridgeSDK.js"></script>

API Reference

const connection = await sdk.init();
if (connection.status === 'READY') {
    console.log("Connected as:", connection.localPseudonym);
}

const peers = await sdk.getPeers();
// peer object: { id: string, pseudonym: string, verified: boolean, isActiveOnApp: boolean }

const getAuthorName = (peerId) => {
    if (peerId === sdk.localPeerId) return sdk.localPseudonym;
    const peer = peers.find(p => p.id === peerId);
    return peer ? peer.pseudonym : peerId.substring(0, 8);
};

sdk.onPeersUpdate((peers) => {
    const onlinePeers = peers.filter(p => p.isActuallyOnline);
    updatePresenceDots(onlinePeers);
}, { cycleMs: 3000 }); // Optional: check every 3s

const targets = ['peer_xyz...'];
const data = { action: 'move', x: 10, y: 20 };
sdk.sendData(targets, data);

sdk.onData((fromPeerId, payload) => {
    console.log(`Message from ${fromPeerId}:`, payload);
});

sdk.onProfileUpdate((newPseudonym) => {
    document.getElementById('display-name').textContent = newPseudonym;
});

const timeStr = await sdk.getServerTime(); 
// Returns string format: YYYYMMDDHHMMSS (e.g. "20260202101030")

// Close the app when the user clicks a "Quit" button
document.getElementById('quit-btn').onclick = () => sdk.closeApp();

// Post Text
const id = await sdk.postMessage({ text: "Hello!" });

// Post Image/File
sdk.postMessage({ 
    file: { 
        name: "image.png", 
        type: "image/png", 
        data: "data:image/png;base64,..." 
    } 
});

await sdk.editMessage("msg_123...", "Updated text content");

// From a configuration popup:
sdk.postAppContent("https://vote.app/", { 
    question: "Pizza or Tacos?", 
    votes: {} 
}, { 
    interactionModel: 'COLLABORATIVE' 
});

// On app startup inside the chat:
const state = await sdk.getAppContext();
console.log("Question:", state.question);

// When a user interacts (e.g. votes):
state.votes[sdk.localPeerId] = "Pizza";
sdk.updateAppContext(state); 
// Result: All channel members see the update instantly.

const mode = sdk.getDisplayMode();

if (mode === 'MESSAGE') {
    renderCompactView(); // Simplified UI for the chat timeline
} else {
    renderFullEditor();  // Full UI for configuration or popups
}

sdk.onContextUpdate((updatedContext) => {
    console.log("New votes received!");
    refreshUI(updatedContext.votes);
});

const mid = sdk.getMessageId();
console.log("This app instance belongs to message:", mid);

// Example: Cast a vote in a poll
sdk.emitAppEvent({ vote: 'Option A' });

sdk.onAppEvent((senderId, data, timestamp) => {
    console.log(`User ${senderId} voted for:`, data.vote);
    recalculateUI();
});

// On startup: Replay history to show the current score
const events = await sdk.getAppEvents();
events.forEach(e => processVote(e.senderId, e.data.vote));

// Switch the app to total fullscreen
sdk.setFullscreen('VIEWPORT');

await sdk.exitFullscreen();

const isAdmin = sdk.getIsAdmin();

if (isAdmin) {
    renderAdminControls(); // Enable configuration or moderation tools
} else {
    renderUserView();      // Restrict UI to standard participation
}

Publishing & Deployment

Once your micro-app is built and hosted on your servers, you have two ways to bring it into iCanText:

1. Sideloading (For Testing & Private Tools)

Any user can manually launch a web-hosted app by typing /app https://your-domain.com in the chat. This is perfect for local development, private testing, or internal company tools.

2. The Official iCanText Store

For public distribution, you can submit your application to the iCanText Store. Apps installed via the official store benefit from major advantages:

• Discoverability: Users can browse and install your app directly via the channel UI.
• Channel Header Integration: Installed apps get a permanent, pinned icon in the channel's top bar for quick access by all members.
• Unrestricted Performance: Official apps bypass the standard anti-flood rate limits, allowing for high-frequency data exchanges (crucial for multiplayer games or live collaborative cursors).

SDK License & Source Code

The SDK is a zero-dependency JavaScript class. It is designed to be robust against standalone execution and elegantly handles the multiplexing of postMessage signals between iCanText and your application logic.

/* SDK code loading... */

Usage Example: Shared Sticky Notes

Below is a minimal example of a collaborative app where users send notes to each other.

const sdk = new ICTBridgeSDK('my_collab_app');

async function startApp() {
    const connection = await sdk.init();
    
    if (connection.status === 'READY') {
        console.log(`Connected as: ${connection.localPseudonym}`);

        // Listen for incoming notes
        sdk.onData((from, payload) => {
            alert(`Note from ${from}: ${payload.text}`);
        });

        // Send a note to all known peers
        const peers = await sdk.getPeers();
        const peerIds = peers.map(p => p.id);
        sdk.sendData(peerIds, { text: 'Hello decentralized world!' });
    }
}

startApp();

Complete Usage Example

This example shows a simple "Status Update" app. When launched through iCanText, it fetches your contacts and allows you to broadcast your current activity to them.

// 1. Initialize the SDK with a unique Application ID
		const sdk = new ICTBridgeSDK('p2p_status_tracker');

		async function setup() {
		    // 2. Start the handshake with the parent iCanText window
		    const connection = await sdk.init();

		    if (connection.status === 'STANDALONE') {
			showUIError('Please launch this app from within iCanText using /app');
			return;
		    }

		    // 3. Handle incoming data from other peers
		    sdk.onData((senderId, payload) => {
			console.log(`Peer ${senderId} is now: ${payload.status}`);
			updateStatusBoard(senderId, payload.status);
		    });

		    // 4. Discovery: Fetch the list of peers in the current Workspace
		    const peers = await sdk.getPeers();
		    renderContactList(peers);
		}

		// 5. Sending Data: Encrypted P2P transmission
		function broadcastMyStatus(newStatus) {
		    sdk.getPeers().then(peers => {
			const targetIds = peers.map(p => p.id);
			
			// This JSON object will be E2EE encrypted and routed via Sealed Forward
			const packet = { 
			    type: 'STATUS_UPDATE', 
			    status: newStatus,
			    timestamp: Date.now() 
			};

			sdk.sendData(targetIds, packet);
		    });
		}

		setup();

async function sayHello() {
    // 1. Create the message
    const msgId = await sdk.postMessage({ 
        text: "I am computing the results..." 
    });
    
    // 2. Simulate work and update the same message
    setTimeout(async () => {
        await sdk.editMessage(msgId, "Computation complete: 42 ✅");
    }, 3000);
}

// The author creates the poll message
sdk.postAppContent("https://poll.app/", 
    { question: "Which consensus is best?" }, 
    { interactionModel: 'OWNER_ONLY' } // Protect the question
);

const voteTally = {};

async function start() {
    await sdk.init();

    // Replay all votes from the Ledger (even if the author is offline)
    const history = await sdk.getAppEvents();
    history.forEach(evt => countVote(evt.senderId, evt.data.choice));

    // Listen for incoming votes from peers
    sdk.onAppEvent((senderId, data) => {
        countVote(senderId, data.choice);
        updateCharts();
    });
}

function castVote(myChoice) {
    // Anyone can emit an event, even if they don't own the parent message
    sdk.emitAppEvent({ choice: myChoice });
}

// list.php
<?php
$allowed_origins = [
    "https://icantext.com",
    "null" // Required for sandboxed iframes
];

if (isset($_SERVER['HTTP_ORIGIN'])) {
    $origin = $_SERVER['HTTP_ORIGIN'];
    if (in_array($origin, $allowed_origins)) {
        header("Access-Control-Allow-Origin: " . $origin);
        header("Access-Control-Allow-Credentials: true");
    }
}
// ... your logic here

const connection = await sdk.init();

if (connection.status === 'STANDALONE') {
    // Show the "How to install" guide or app description
    renderLandingPage(); 
} else {
    // Start the collaborative real-time logic
    initializeP2PLogic();
}

Best Practices

• Handle Disconnections: Always check window.opener before sending data; if the user closes iCanText, the bridge will break.
• Payload Size: While the P2P layer handles fragmentation, keep payloads under 1MB for optimal performance across the mesh.
• Origin Security: The SDK automatically ensures messages are only exchanged with the domain that launched the app.
• Validation: Always validate the structure of the payload received in onData as it comes from a remote peer's application instance.
• Frame Permissions: Your server must allow your app to be embedded in an iframe. Ensure your Content-Security-Policy does not have a restrictive frame-ancestors directive, and avoid the X-Frame-Options: DENY header.
• Choosing the right Model: Use updateAppContext for small, non-conflicting metadata (like the name of a room). Use Event Sourcing (emitAppEvent) for collaborative tools where multiple users act simultaneously to avoid data loss.
• Universal Ledger Lifecycle: When an app-event is emitted, it is stored by all peers in a dedicated memory space called the Ledger. This ledger is not limited by the standard 50-message chat history. However, to prevent memory leaks, iCanText automatically wipes the entire ledger of an app as soon as its parent message is deleted or expires.
• Decentralized Presence: When using onPeersUpdate, presence is reached via consensus. If a user closes their tab without signaling, they will transition to SUSPECT then OFFLINE within 3 cycles. This prevents "ghost" users in the UI while keeping network traffic minimal.
• Visual Comfort: Avoid forcing VIEWPORT fullscreen immediately upon app launch. Let the user trigger the expansion via a dedicated button to avoid breaking their reading flow.