Engine and website parity work

Executive Summary

The workbench was moved from a website-first prototype toward a KMM Reaktor module where the engine and website share the same domain model, graph, fixtures, services, interactors, app targets, design vocabulary, and most renderer-facing state.

Module Shape

The target shape is now a Reaktor KMM workbench module. The common layer owns vocabulary and behavior; the platform layers render and bridge external UI libraries.

modules/engine/
  src/commonMain/kotlin/ai/bestbuds/reaktor/workbench/
    data/
      actors/
      core/
      interactors/
      repositories/
      services/
    design/
    fixtures/
    graph/
      panes/
    model/
    ui/compose/

  src/jsMain/kotlin/ai/bestbuds/reaktor/workbench/render/react/
    atoms/
    domain/
    foundation/
    graph/
    panels/
    runtime/
    shell/
    state/

  src/jsMain/react/
    main.ts
    styles.css
    styles-v3.css

  src/jvmMain/kotlin/ai/bestbuds/reaktor/workbench/render/compose/
    atoms/
    design/
    graph/
    inspection/
    panes/
    shell/

Shared Kotlin Core

The common layer now carries the workbench meaning. Renderers should mostly project this meaning instead of inventing parallel state machines.

Common service surface

The shared service layer now defines the same operations the UI presents. These are mock-backed today, but they are typed service contracts rather than loose UI-only fixtures.

Website Renderer

The website renderer was moved from a JSX-heavy tree into Kotlin/JS. The remaining TypeScript file is now intentionally small and platform-like: it installs React, loads CSS, lazy-loads React Flow, installs Kotlin bridge objects, and boots the Kotlin app component.

Kotlin/React decomposition

Website behavior implemented

• Target switching now has the real app set: BestBuds, Engine, and Website.
• The graph screen uses the BestBuds graph export and maps it into the workbench catalog.
• Graph node sizing and visual density were improved through shared graph visuals and larger readable node surfaces.
• All major modes have real screens or mock-backed rich screens instead of empty tab placeholders.
• DevTools is the canonical name; Run remains a retired concept.
• Performance marks are emitted during runtime import, graph import, graph boot scheduling, and graph boot completion.

Desktop Engine

The desktop app now follows the website as the styling source of truth. The work focused on making Compose render the same control-plane vocabulary as the web app: dark chrome, compact top bar, mode toolbar, graph drawer, right inspector, bottom command drawer, DevTools command pipeline, and graph-focused panes.

Feature Parity

The current state is not that every backend integration is production-real. The important shift is that both renderers now see the same workbench world and can mix live graph data with mock-backed subsystem contracts without deleting unfinished surfaces.

Tests and Performance

The test work expanded in three directions: common engine behavior, desktop renderer smoke coverage, and website browser coverage. Performance harnessing also moved toward a dedicated reaktor-performance concern.

Real vs Mock

The direction is intentionally mixed: real where the codebase already has reliable source data, mock-backed where the subsystem surface is needed for parity but the backend is not ready.

Pain Points Found

The implementation worked, but it exposed where Reaktor Graph and the workbench architecture should become sharper.

Reaktor Graph Enhancements

The next graph work should reduce hand wiring while increasing introspection. The goal is the same BestBuds principle: fewer concepts, more expression, less bloat.

workbenchPane(WorkbenchMode.DevTools) {
  route("/devtools")
  graph(::WorkbenchDevtoolsPaneGraph)
  expose(::DevToolsInteractor)
}

Next Steps

1. Build the pane/route DSL inside reaktor-graph, then rewrite WorkbenchGraph to prove the API reduces boilerplate.
2. Add GraphInspector and surface its diagnostics in both the website and desktop Graph pane.
3. Move graph visual sizing, handles, grouping, and layout hints into a common ReaktorFlowVisualGraph model.
4. Turn the remaining TypeScript bridge into a small generated runtime adapter with explicit lazy-load hooks.
5. Make subsystem maturity real in the graph: live, typed mock, stub, production adapter, deployable, and blocked.
6. Add shared exact test IDs and semantics tags so Playwright and Compose tests can use the same intent names.
7. Replace mock subsystem services one by one behind the existing common service APIs without changing the renderer contracts.

File Map