Genesis OS - Developer Documentation

Introduction to App Development

Welcome to the Genesis OS developer documentation. This guide provides the technical details required to build, test, and submit external applications for the operating system.

Applications in Genesis OS are composed of two core components:

A JSON Manifest: A metadata file that describes your application to the OS.
A JavaScript Entry Point: A single JavaScript file that contains your application's logic and is executed within a sandboxed environment.

This modular approach allows for secure, dynamic loading of applications without requiring changes to the core OS codebase.

The Application Manifest

The manifest is a JSON file (e.g., my-app.json) that tells Genesis OS everything it needs to know about your application, from its name and icon to its window size and entry point.

Manifest Properties

Property	Type	Description	Required
`id`	String	A unique, URL-safe identifier for your app (e.g., "word-processor").	Yes
`title`	String	The human-readable name of the application displayed in the UI.	Yes
`entry`	String	The filename of the main JavaScript file (e.g., "app.js").	Yes
`description`	String	A brief summary of what your application does.	No
`icon`	String	An emoji character to represent your app on the desktop and taskbar.	No
`category`	String	The category your app belongs to (e.g., "Utilities", "Development", "Games").	No
`version`	String	The version number of your application (e.g., "1.0.0").	No
`window`	Object	An object defining the default properties of the application window.	No

Example Manifest

{
  "id": "hello-world-app",
  "title": "Hello World",
  "description": "A simple demonstration application.",
  "icon": "👋",
  "category": "Utilities",
  "version": "1.0.0",
  "entry": "hello-world.js",
  "window": {
    "width": 400,
    "height": 300,
    "resizable": false
  }
}

The Entry Point: `initialize(GOS)`

Your application's JavaScript file must export a single function named initialize. When a user launches your app, Genesis OS will load this script as an ES module and call this function, passing a single argument: the GOS API object.

The `GOS` API Object

The GOS object is your application's bridge to the operating system. It provides access to sandboxed UI elements and core system services.

Property	Description
`GOS.app`	Contains metadata about the currently running app (id, title, version).
`GOS.user`	Contains information about the logged-in user (username, name, roles).
`GOS.window`	Provides methods to interact with the application's window and its content area.
`GOS.filesystem`	Provides methods for interacting with the virtual filesystem.
`GOS.ui`	Provides methods for showing OS-level UI elements like dialogs and notifications.

The Sandbox Environment

For security and stability, every external application runs within its own sandboxed <iframe>. This means your application's script does not have direct access to the main OS document.

Accessing the DOM

To add HTML and CSS to your application's window, you must use the container element provided by the GOS API. This ensures your UI is rendered inside the correct iframe.

export function initialize(GOS) {
    // Get the document object of the sandboxed iframe
    const doc = GOS.window.getContainer().ownerDocument;

    // Get the body of the iframe to inject your HTML
    const body = doc.body;

    // Inject your application's UI
    body.innerHTML = `<h1>Hello, ${GOS.user.name}!</h1>`;
}

Important: When creating UI elements or adding event listeners, always use the sandboxed doc object (e.g., doc.createElement(), doc.getElementById()) instead of the global document.

Using the GOS API

The GOS object provides a clean and secure way to perform common tasks.

Displaying a Dialog

Use GOS.ui.showDialog() to show a modal dialog. This function returns a Promise that resolves when the user closes the dialog.

async function askForName(GOS) {
    const dialogBody = `<div class="form-row">
        <label for="userName">Please enter your name:</label>
        <input type="text" id="userName">
    </div>`;

    const getFormData = () => ({
        name: window.parent.document.getElementById('userName').value
    });

    const result = await GOS.ui.showDialog('Greeting', dialogBody, { 
        buttons: ['Cancel', 'Submit'],
        getFormData: getFormData 
    });

    if (result.button === 'Submit' && result.formData.name) {
        GOS.ui.showNotification('Success', `Hello, ${result.formData.name}!`);
    }
}

Note on Dialogs: Because dialogs are rendered in the main OS document, the getFormData callback must use window.parent.document.getElementById() to find the input elements correctly.

Showing a Notification

Use GOS.ui.showNotification() to display a non-blocking "toast" message.

GOS.ui.showNotification(
    'File Saved', 
    'Your document was saved successfully.',
    3000 // Duration in milliseconds
);

Reading a File

Use the asynchronous GOS.filesystem.readFile() method.

async function loadConfig(GOS) {
    try {
        const filePath = `/users/${GOS.user.username}/Documents/config.txt`;
        const file = await GOS.filesystem.readFile(filePath);
        console.log('File content:', file.content);
    } catch (error) {
        GOS.ui.showNotification('Error', 'Could not read config file.', 4000);
    }
}

Full "Hello World" Example

Here are the two files needed for a complete, installable "Hello World" application.

1. Manifest: `hello-world.json`

{
  "id": "hello-world",
  "title": "Hello World",
  "description": "A simple demonstration application.",
  "icon": "👋",
  "version": "1.0.0",
  "entry": "hello-world.js",
  "window": {
    "width": 450,
    "height": 250,
    "resizable": false
  }
}

2. Entry Point: `hello-world.js`

export function initialize(GOS) {
    const doc = GOS.window.getContainer().ownerDocument;
    const body = doc.body;

    // Apply some basic styling
    const style = doc.createElement('style');
    style.textContent = \`
        body { 
            display: flex; 
            align-items: center; 
            justify-content: center; 
            text-align: center; 
            font-family: sans-serif;
            background-color: #2c2c2c;
            color: #f0f0f0;
        }
        button { 
            padding: 10px 20px; 
            font-size: 1rem; 
            margin-top: 20px; 
            cursor: pointer;
            border: 1px solid #555;
            background-color: #444;
            color: #fff;
            border-radius: 5px;
        }
    \`;
    doc.head.appendChild(style);

    // Set the initial HTML content
    body.innerHTML = \`
        <div>
            <h1>Hello, ${GOS.user.name}!</h1>
            <p>This is your first Genesis OS application.</p>
            <button id="greetBtn">Click Me</button>
        </div>
    \`;

    // Add an event listener
    const greetBtn = doc.getElementById('greetBtn');
    greetBtn.addEventListener('click', () => {
        GOS.ui.showNotification(
            'Greetings!',
            'You clicked the button!',
            2500
        );
    });
}

Submission Process

Once your application is complete, you can submit it for review through the **Developer Center** application within Genesis OS.

Launch the "Developer Center" application from the desktop or start menu.
Copy the entire contents of your JSON manifest file and paste it into the "Manifest" text area.
Copy the entire contents of your JavaScript entry point file and paste it into the "Application Code" text area.
Click the "Submit for Review" button.

An administrator will review your submission. If approved, your application will be installed into the `/apps/` directory and will become available to all users in the App Store.

GOS Docs