Cheetah / Cheetah documentation

A self-contained browser action

A useful Cheetah application does not always need a server. A browser extension can keep the application-facing command API, the shared client runtime, its handlers, and its product state inside the extension. This is Local Mode: the command still follows Cheetah's validation and dispatch pipeline, but it crosses an in-memory transport instead of a network.

Local Mode is a complete shape in its own right. The connected shapes are options when a product needs remote coordination, not required graduation stages.

What createLocalApp() assembles

createLocalApp() creates a browser runtime and a small local application node connected by an in-memory WebSocket pair. The runtime uses the same dispatcher and handler contracts as a connected browser client. Starting the pair performs the local hello exchange and makes the runtime's registered actions available to the local application side.

The smallest verified round trip is:

import { createLocalApp } from '@cheetah/browser';

const local = await createLocalApp();

try {
  await local.start();
  const result = await local.app.sendCommand('echo', { message: 'hello' });

  if (result.status !== 'applied') {
    throw new Error(result.error?.message ?? 'The local action failed');
  }

  console.log(result.payload);
} finally {
  await local.stop();
}

The maintained Local Mode tests exercise construction, the hello handshake, successful echo and ping results, unknown-action failures, sequential commands, timeouts, duplicate terminal results, state-report listeners, and disposal. This is a real command pipeline; it is not a direct function call disguised as one.

Add product behavior at the handler boundary

A product normally registers a narrow handler before starting the runtime. In a browser extension that handler may use the content-script bridge to read a page, call an allowed Chrome API, or combine locally stored product state with the command parameters. Its result returns through LocalAppNode.sendCommand() as an applied or failed command result.

Keep application concerns outside the shared runtime. A queue of pages, a saved research record, or a domain-specific parser belongs to the extension. Cheetah supplies the command and handler lifecycle, built-in browser actions, target addressing, local policy and approval hooks, leases, structured outcomes, and browser adapters.

This separation matters when a Manifest V3 service worker is evicted. Cheetah can rebuild its runtime identity and browser-facing machinery, but the product must persist any queue or business state that must survive. chrome.storage.local, an external database, or deliberate reconstruction from current tabs are product choices with different consistency properties.

Know what is absent

Local Mode has no WebSocket server role, returned-data HTTP role, remote application role, central connection registry, server history, cross-client routing, or distributed coordination. A local result is available to the in-extension caller; it is not automatically retained as server evidence.

Removing the network also does not remove browser failure modes. Tabs close, content scripts may be missing, extension permissions can change, and the service worker can disappear between events. The product still needs clear recovery behavior and must check every command result before changing durable product state.

Worker placement is also explicit. create_tab with worker: true needs a suitable worker-owned window or an explicit placement decision. A product must provision or select that window and count a tab only after the returned command says it was applied. Sending the command is not evidence that Chrome created the tab.

Grow only when the requirement appears

If the product later needs another computer, several independently connected clients, central policy, or retained server-side evidence, replace the in-memory boundary with a connected runtime and a server composition. The action name, parameters, handler, target, local authority, and result shape can remain recognizable.

That continuity is the benefit of Local Mode. It lets a product begin with the smallest honest topology without creating a second programming model that must be discarded later.

Continue with one connected client