Mode 1 OS

kernel-os.js
Full OS kernel.

The default kernel. Includes booting, error handling, routing, services, the AppStore, the Firebase cloud subsystem, and kernel.launch() for running apps in iframes. Use this when you're building a browser-based operating system with a desktop UI.

Getting started

Drop in the script tag and call onReady(). The kernel handles its own boot sequence — the black screen appears automatically and disappears once booting is complete.

index.html

<script src="https://webnux.pages.dev/kernel-os.js"></script>
<script>
  WebOSKernel.onReady(kernel => {
    // your OS starts here
    document.body.innerHTML = '<div id="desktop"></div>';
  });
</script>

App Store

Register apps with kernel.appStore.register(meta). Apps with store: true are persisted to localStorage and visible to any other WebOS on the same origin running the same kernel version.

my-os.js

WebOSKernel.onReady(kernel => {
  // register a local app
  kernel.appStore.register({
    id:            'com.example.notes',
    name:          'Notes',
    version:       '1.0.0',
    kernelVersion: '1.0.0',
    store:         true,
    sourceCode:    '<h1>My Notes App</h1>',
  });

  // list all available apps
  const apps = kernel.appStore.list();
  console.log(apps);
});

Cloud

The cloud subsystem connects to Firebase lazily — no overhead unless you use it. loadApps() fetches the apps Firestore collection and registers everything into the AppStore automatically. You can also fetch any collection yourself.

my-os.js

WebOSKernel.onReady(async kernel => {
  // pull all cloud apps into the AppStore
  await kernel.cloud.loadApps();

  // fetch any Firestore collection
  const settings = await kernel.cloud.fetch('settings');

  // get a single app document from Firestore
  const app = await kernel.cloud.getApp('com.example.notes');
});

Launching apps

kernel.launch(appId) walks the full pipeline — checks the local AppStore, falls back to Firebase, builds a sandboxed iframe, and returns it ready to place anywhere in your OS UI.

my-os.js

WebOSKernel.onReady(async kernel => {
  const iframe = await kernel.launch('com.example.notes');

  // place it wherever your OS puts windows
  document.getElementById('window-container').appendChild(iframe);

  // listen for when the app is fully loaded
  kernel.events.on('app:ready', ({ name, iframe }) => {
    console.log(`${name} is live`);
  });
});

ℹ️

The app document in Firestore needs either a sourceCode field (raw HTML/JS string) or an entry field (a public URL). If neither is present, launch() throws WK_E008.

Events

The OS kernel emits the following events you can listen to with kernel.events.on(event, fn).

Event	Payload	When
kernel:booting	{ version }	Boot sequence starts
kernel:ready	{ version }	Boot complete, onReady() fires
cloud:connected	—	Firebase first connected
cloud:app:fetched	{ ...appData }	A single app retrieved from Firestore
cloud:apps:loaded	{ count }	loadApps() finished
app:requesting	{ id }	launch() started
app:found	{ id, name }	App data located
app:launching	{ id, name }	iframe being built
app:ready	{ id, name, iframe }	iframe loaded
app:error	{ id, error }	launch() failed
appstore:registered	{ id, name }	App registered in AppStore
service:registered	{ name }	Service registered

API reference

Method	Description
kernel.onReady(cb)	Register a callback to run after boot. Safe to call before or after boot.
kernel.launch(appId)	Full app pipeline. Returns a sandboxed HTMLIFrameElement.
kernel.register(name, svc)	Register a named service.
kernel.resolve(name)	Get a registered service. Throws WK_E005 if not found.
kernel.use(fn)	Add middleware to the request pipeline.
kernel.plugin({ name, install })	Install a plugin.
kernel.handle(method, url)	Dispatch a request through the router.
kernel.uptime()	Seconds since boot.
kernel.appStore.register(meta)	Register an app locally (and optionally to localStorage).
kernel.appStore.list()	List all apps (local + persisted).
kernel.appStore.get(id)	Get a single app by id.
kernel.cloud.loadApps()	Fetch the Firestore apps collection and register all into AppStore.
kernel.cloud.fetch(collection)	Fetch all documents from any Firestore collection.
kernel.cloud.getApp(id)	Fetch a single app document from Firestore by id.
kernel.events.on(event, fn)	Subscribe to a kernel event.
kernel.events.once(event, fn)	Subscribe once, then auto-unsubscribe.
kernel.events.emit(event, data)	Emit a custom event.
kernel.router.get/post/put/delete(path, handler)	Register a route handler.

Mode 2 SMS

kernel-sms.js
Messaging kernel.

A trimmed kernel for conversation-driven WebOSes. No AppStore, no launch(). Adds cloud.send() for writing messages to Firestore and cloud.subscribe() for real-time updates via onSnapshot.

Getting started

Same drop-in pattern as Mode 1 — just swap the file.

index.html

<script src="https://webnux.pages.dev/kernel-sms.js"></script>
<script>
  WebOSKernel.onReady(kernel => {
    // your messaging OS starts here
  });
</script>

Sending messages

kernel.cloud.send(collection, message) writes a document to Firestore and automatically stamps it with a server timestamp. Returns the new document ID.

my-sms-os.js

WebOSKernel.onReady(async kernel => {
  const id = await kernel.cloud.send('messages', {
    from:    'alice',
    text:    'Hello!',
    channel: 'general',
  });
  console.log('Sent, doc id:', id);
});

Real-time updates

kernel.cloud.subscribe(collection, callback) opens a Firestore onSnapshot listener. Messages are delivered in ascending timestamp order. Returns an unsubscribe function.

my-sms-os.js

WebOSKernel.onReady(async kernel => {
  // subscribe — fires immediately with existing messages,
  // then again every time a new message arrives
  const unsub = await kernel.cloud.subscribe('messages', messages => {
    renderMessages(messages);
  });

  // call unsub() to stop listening when needed
  document.getElementById('leave-btn').onclick = () => unsub();
});

⚠️

The SMS kernel also emits cloud:messages:updated every time the snapshot fires, so you can react to new messages from anywhere using kernel.events.on() instead of a callback.

Events

Event	Payload	When
kernel:booting	{ version, mode }	Boot sequence starts
kernel:ready	{ version, mode }	Boot complete
cloud:connected	—	Firebase first connected
cloud:message:sent	{ id, collection }	send() completed
cloud:messages:updated	{ collection, messages }	subscribe() snapshot fires
service:registered	{ name }	Service registered

API reference

Method	Description
kernel.onReady(cb)	Register a callback to run after boot.
kernel.register(name, svc)	Register a named service.
kernel.resolve(name)	Get a registered service.
kernel.use(fn)	Add middleware to the request pipeline.
kernel.plugin({ name, install })	Install a plugin.
kernel.cloud.send(collection, message)	Write a message doc to Firestore. Returns the new doc ID.
kernel.cloud.subscribe(collection, cb)	Real-time Firestore listener. Returns unsubscribe function.
kernel.cloud.fetch(collection)	One-time fetch of all docs in a collection.
kernel.events.on(event, fn)	Subscribe to a kernel event.
kernel.events.once(event, fn)	Subscribe once.
kernel.events.emit(event, data)	Emit a custom event.

Mode 3 Tools Headless

kernel-tools.js
Headless kernel.

No UI, no boot screen, no app launching. Boots instantly and registers four built-in tool services: dev:console, dev:inspector, util:calc, and util:notes. Wire up your own UI to whichever tools you need.

Getting started

The Tools kernel boots headlessly — no DOM overlay, no delay. onReady() fires as soon as the script loads and all services are registered.

index.html

<script src="https://webnux.pages.dev/kernel-tools.js"></script>
<script>
  WebOSKernel.onReady(kernel => {
    const con = kernel.resolve('dev:console');
    const ins = kernel.resolve('dev:inspector');
    const cal = kernel.resolve('util:calc');
    const nts = kernel.resolve('util:notes');
  });
</script>

dev:console

Intercepts all console.log, warn, error, info, and debug calls from the moment the kernel loads. Lets you build a visible log panel in your UI.

my-tools-os.js

const con = kernel.resolve('dev:console');

con.history();         // all captured entries
con.tail(50);          // last 50 entries
con.filter('error');   // only errors
con.clear();           // wipe history

dev:inspector

Dumps a snapshot of the current kernel state — uptime, services, plugins, routes, and heap memory. Useful for a debug panel or a status bar in your UI.

my-tools-os.js

const ins = kernel.resolve('dev:inspector');

const snap = ins.snapshot();  // returns state object
ins.print();                  // logs it to console in a group

// snap looks like:
// { version, mode, booted, uptime, services,
//   plugins, routes, memoryMB, timestamp }

util:calc

A safe expression evaluator. Strips anything that isn't a number, operator, or parenthesis before evaluating — no arbitrary code execution.

my-tools-os.js

const cal = kernel.resolve('util:calc');

cal.evaluate('2 + 2');          // 4
cal.evaluate('(10 * 3) / 2');  // 15
cal.evaluate('100 % 7');        // 2

util:notes

An in-memory key/value note store. Notes are session-only — they don't persist to localStorage or Firestore unless you wire that up yourself.

my-tools-os.js

const nts = kernel.resolve('util:notes');

nts.set('todo', 'Fix the kernel');
nts.get('todo');                  // { id, content, updatedAt }
nts.list();                       // all notes
nts.search('kernel');             // notes matching substring
nts.delete('todo');               // remove a note

API reference

Service / Method	Description
dev:console.history()	All captured log entries.
dev:console.tail(n)	Last n entries (default 50).
dev:console.filter(level)	Entries matching a log level (log, warn, error, info, debug).
dev:console.clear()	Clear the log history.
dev:inspector.snapshot()	Returns a kernel state object.
dev:inspector.print()	Logs a formatted snapshot to the console.
util:calc.evaluate(expr)	Evaluate a math expression string. Returns a number.
util:notes.set(id, content)	Create or update a note. Returns the note object.
util:notes.get(id)	Get a note by id. Returns null if not found.
util:notes.list()	All notes as an array.
util:notes.search(query)	Notes whose content includes the query string.
util:notes.delete(id)	Delete a note.

Mode 4 Mode 5 Auth

kernel-os-login.js
kernel-sms-login.js
With authentication.

Modes 4 and 5 are identical to Modes 1 and 2 respectively — same API, same events, same everything — with one addition: the kernel holds the boot sequence behind a login screen until the user authenticates via Firebase Auth. onReady() only fires after a successful sign-in.

🔑

If a Firebase Auth session already exists from a previous page load, the login screen is skipped automatically and the kernel boots straight through. No extra code needed.

The auth subsystem

kernel.auth is available inside onReady() with the current authenticated user already set.

my-os.js

WebOSKernel.onReady(async kernel => {
  // user is guaranteed to be signed in here
  console.log(kernel.auth.currentUser.email);

  // sign the user out (returns to login screen on next load)
  await kernel.auth.signOut();
});

Method	Description
kernel.auth.currentUser	The Firebase User object. Always set inside onReady().
kernel.auth.signIn(email, password)	Sign in manually (handled automatically by the login screen).
kernel.auth.signOut()	Sign the current user out.
kernel.auth.restoreSession()	Check for an existing Firebase session. Called automatically during boot.

Event	Payload	When
auth:signed-in	{ user }	User authenticated successfully
auth:signed-out	—	signOut() completed
auth:error	{ message }	Sign-in attempt failed

kernel-os.jsFull OS kernel.

Getting started

App Store

Cloud

Launching apps

Events

API reference

kernel-sms.jsMessaging kernel.

Getting started

Sending messages

Real-time updates

Events

API reference

kernel-tools.jsHeadless kernel.

Getting started

dev:console

dev:inspector

util:calc

util:notes

API reference

kernel-os-login.jskernel-sms-login.jsWith authentication.

The auth subsystem

kernel-os.js
Full OS kernel.

kernel-sms.js
Messaging kernel.

kernel-tools.js
Headless kernel.

kernel-os-login.js
kernel-sms-login.js
With authentication.