Architecture and Bootstrap

Architecture and Bootstrap

Allislet v1.0.0-alpha follows a deliberately small bootstrap model that keeps the host page stable while exposing a high-control overlay runtime. The system is designed around a mountable host container, a private context provider, and a set of singleton services that manage runtime activity across the injected application.

High-level architecture

The SDK is organized into layered stages that build upward from secure foundational primitives into automation and interaction features.

Stage 1: core and foundations

This stage establishes the runtime primitives required for isolated injection and storage.

• GlobalStorage: coordinates cross-domain storage and communication boundaries
• StorageNamespace: prefixes keys for deterministic storage isolation
• StatePersist: persists app state across lifecycle boundaries
• EncryptedStore: uses WebCrypto AES encryption for sensitive local data
• ShadowMount: manages per-instance mount isolation
• HostReset: applies host-safe resets and isolated styling boundaries
• Lifecycle: centralizes cleanup registration and teardown handlers
• defineConfig: creates config objects and merges default runtime behavior
• EventBus: a shared message and event channel for app-level coordination

Stage 2: execution and sockets

This stage is responsible for runtime execution and host-side instrumentation.

• PageExecutor: executes code in the page runtime and coordinate main-thread actions
• CSPSafe: injects scripts in a CSP-safe way using Blob-based execution paths
• AntiDetect: strips sensitive stack traces and randomizes execution markers
• ServiceWorkerRegistrar: registers or manages service worker behavior
• WebSocketManager: tracks active connections, forced disconnects, and socket lock states
• SocketIoBridge: bridges socket notifications and events into app-level services
• patchFetch and patchXHR: intercept requests for logging, shaping, and testing
• NetworkMock: simulates silent 200 responses, drops, or latency injection
• BearerExtractor: extracts JWT values and token-bearing metadata from request flows

Stage 3: DOM control and automation

This stage provides the browser automation layer and UI interaction controls.

• DOMObserver: wraps MutationObserver with structured listeners and updates
• teleport: a portal-style abstraction for rendering into arbitrary host nodes
• MacroRecorder: records user clicks, inputs, scrolls, and interactions for replay
• ElementPicker: enables cursor-based DOM inspection and targeting
• Highlighter: draws non-destructive visual overlays for inspection targets
• DOMFinder: resolves DOM nodes using XPath and innerText strategies
• FormAutofill: fills forms and form fields based on structured automation rules

Stage 4: layouts, themes, and feedback

This stage includes overlay controls and visual shell tools.

• DockManager: supports left, right, top, and bottom docking layouts
• WindowManager: opens floating windows with sub-sidebars and custom views
• DragController: manages draggable windows and configurable interaction constraints
• Modal: overlays and modal lifecycle controls
• Theme Engine: supports accent styles, dark mode and light mode themes
• CommandRegistry: provides Ctrl+K palette style command access
• Toast System: publishes info, success, warning, and custom notification patterns
• ErrorBoundary: isolates and renders recoverable app errors

Stage 5: utilities and data extraction

This layer expands the SDK into a browser automation and data-extraction toolkit.

• URLState: binds UI state to URL parameters
• TabBroadcast: synchronizes state across tabs using BroadcastChannel
• PageRouter: manages route-aware app state transitions
• DeepLink: enables deep-link access and navigation routing
• TableScraper: transforms table markup into structured JSON
• CSVExporter and JSONExporter: export data in common formats
• ScreenCapture: captures canvas and node screenshot output
• FileSystemAccess: exposes safe file-system interactions when available
• IndexedDBExplorer: reads and inspects IndexedDB databases
• CookieManager: reads and manipulates cookies with required scoping
• PerfProfiler: measures runtime and rendering performance
• ConsoleRedirector: redirects console streams into the SDK view layer
• AsyncQueue: manages queued async workflows
• CronTask: schedules defined timed tasks
• WorkerOffloader: executes inline Worker tasks off the main thread
• SpeechEngine: handles speech synthesis and voice-driven effects
• Clipboard: exposes clipboard read/write operations
• MediaSniffer: captures media streams from canvas and video sources
• DiffViewer: visual differences between snapshots or rendered states

Stage 6: built-in togglable tabs

The application can expose built-in runtime tabs for operational control.

• Realtime Chat and DM engine
• Username persistence and public room support
• Direct-message delivery via socket.ts
• Remote Execution Admin tab
• AdminStore.isAdmin toggles
• Remote JS payload execution across connected clients
• User mute and user kick controls

Bootstrap entrypoint

The bootstrap sequence begins in src/main.tsx. This is the host-level entrypoint and should be treated as the application root for mount initialization.

The expected execution flow is:

1. Instantiate the runtime mount host
2. Apply HostReset styles inside a closed Shadow Root
3. Mount onto document.body
4. Render the top-level Preact app
5. Initialize singleton runtime services
6. Hydrate data and config and register lifecycle hooks

The main bootstrap pattern looks like this conceptually:

const hostElement = document.createElement("div");
document.body.appendChild(hostElement);

const shadowRoot = hostElement.attachShadow({ mode: "closed" });
const renderTarget = document.createElement("div");
shadowRoot.appendChild(renderTarget);

render(
  <AllisletProvider config={config} eventBus={eventBus} pageExec={pageExec} storage={storage} antiDetect={antiDetect}>
    <App />
  </AllisletProvider>,
  renderTarget
);

This pattern is intentionally designed to keep the host page’s styling, layout, and DOM structure intact while the injected application renders its own isolated shell.

Closed Shadow Root isolation

Allislet relies on a closed Shadow Root in the runtime to isolate:

• CSS inheritance
• layout collisions
• DOM event bubbling assumptions
• host page style overrides
• third-party library visual interference

The host element is positioned and reset using a host-safe stylesheet so the app can behave like a floating viewport without destabilizing the page.

The bootstrap flow uses a fixed-position root plus a render target within the shadow tree. This gives the SDK a stable overlay layer while maintaining encapsulation from the host page.

Global metadata and runtime identity

The SDK exposes global metadata at runtime for app identification, SDK versioning, and configuration introspection.

Typical patterns include:

• app.version
• window.app.version
• config.id
• config.name
• config.version

This metadata is used to keep the runtime aware of the current app identity, which is especially important in multi-instance or multi-tab injection settings.

Preact app shell and provider model

The application root is a Preact tree rendered under a top-level container. The app shell is wrapped in an AllisletProvider which exposes a public context for the rest of the app.

The provider holds singleton service instances such as:

• EventBus
• GlobalStorage
• PageExecutor
• AntiDetect
• associated configuration values

This architecture means that any child component can read runtime state with the hook:

const { pageExec, eventBus, storage, config } = useAllislet();

The provider avoids re-instantiation at every render while preserving a single coherent runtime service registry for the injected app.

Service lifecycle and singleton memory

Allislet uses private runtime memory for service singletons. That pattern is important because it allows the SDK to:

• share one event bus across the app
• coordinate page execution without duplicate workers
• maintain one storage namespace per host/session
• avoid reconfiguring state on every render pass

The lifecycle configuration is passed through defineConfig and optionally invoked on bootstrap and teardown:

export default defineConfig({
  id: "my-app",
  name: "My App",
  version: "v1.0.0-alpha",
  onMount({ eventBus, pageExec }) {
    console.log("Booted");
  },
  onCleanup() {
    console.log("Cleaned up");
  },
});

The app can initialize runtime side effects once during mount and destroy them on unmount or teardown.

Execution pipeline

The runtime execution path is intentionally split between host-side app logic and page-side script execution.

Host side

The host app is the UI runtime. It manages:

• view rendering
• actions and state flow
• command palette interaction
• overlay shell updates
• socket and event coordination

Page side

PageExecutor handles execution inside the target page context, including:

• script injection into main thread contexts
• regulated execution under CSP-safe rules
• anti-detection and instrumentation controls
• runtime evaluation of page-specific payloads

This split keeps the user interface isolated while enabling the SDK to safely interact with the page it is attached to.

Dynamic ingestion and library loading

Allislet supports automated external library loading based on config. The libraries property allows the SDK to declare dependencies that load into the runtime as part of the injection model.

export default defineConfig({
  libraries: [
    { name: "socket.io-client", url: "https://cdn.example.com/socket.io-client.js" },
  ],
});

This supports scenarios where the SDK needs DOM helpers, socket clients, or browser utilities that are not shipped as part of the base bundle.

useData and data fetching

The SDK includes an app-level data helper designed to fetch JSON data from a predictable path. Allislet’s useData hook resolves URLs in a domain-local manner and supports local development overrides.

The fetch behavior is:

• if a custom baseUrl is passed, it is used
• if a global data URL has been set, it is used
• in development mode, the default base is http://localhost:5173/data
• otherwise, the default base will use the current window origin and /data

Example usage:

const result = await useData("settings");

if (result.status === "success") {
  console.log(result.data);
}

If the key does not end in .json, the SDK resolves it as a JSON file name automatically.

So these patterns resolve as follows:

• useData("config") -> /data/config.json
• useData("domain/data") -> /data/domain/data.json
• useData("c") -> /data/c.json

This makes configuration-driven data ingestion simple for local application resources and remote host data sources.

Runtime strategy summary

Allislet is built around a simple conviction: the SDK should work as an overlay, utility, and automation surface without rewriting the host page or destabilizing it.

That is why the architecture emphasizes:

• isolated mounts
• singleton service memory
• config-driven behavior
• host-safe rendering
• runtime execution boundaries
• utility-rich app features

The resulting system is flexible enough to support bookmarklet overlays, injected tools, debugging consoles, admin panels, and app shells in a controlled browser environment.