Web Server Implementation Sharing Between LibreKitten and OmniBlocks

[ampelectrecuted]

Discussed in https://github.com/orgs/OmniBlocks/discussions/765

^{Originally posted by someCatInTheWorld January 31, 2026}
I feel like I still want to work on LK, but I don't want to have the web server features differ too much between these mods. Maybe we could have some kind of implementation sharing between the mods' web servers?

[traycerai]

Plan

Observations

OmniBlocks already registers a 'Web Server' extension (extensionId 'server', collaborator 'LibreKitten') in file:src/lib/libraries/extensions/index.jsx. The actual server-side block implementation lives in the scratch-vm dependency (github:OmniBlocks/scratch-vm#develop). LibreKitten's server runtime is implemented in its own VM fork under packages/vm/src/server/. The existing PLATFORM_MISMATCH event pipeline (file:src/lib/vm-listener-hoc.jsx → file:src/reducers/tw.js → file:src/containers/tw-unknown-platform-modal.jsx) already guards against cross-mod project incompatibilities.

Approach

The cleanest way to share the Web Server extension implementation between the two mods is to make OmniBlocks's scratch-vm consume the canonical server extension blocks from LibreKitten's upstream VM package rather than maintaining a fork of them. On the GUI side, the extension entry, its icon, and any UI helpers are kept in sync through clearly separated, LibreKitten-attributed files. This avoids duplicating logic and keeps feature parity automatic when LibreKitten ships updates.

---

Implementation Plan

1. Establish the canonical server extension source

In the OmniBlocks/scratch-vm repository (the dependency declared in file:package.json as "scratch-vm": "github:OmniBlocks/scratch-vm#develop"):

• Create a src/extensions/scratch3_server/ directory mirroring LibreKitten's server extension structure (packages/vm/src/extensions/scratch3_server/ from the LibreKitten repo).
• The extension class (e.g., Scratch3ServerBlocks) must implement the same getInfo() block definitions, HTTP request/response hat blocks, routing blocks, and response-sending blocks that LibreKitten exposes—keeping opcodes, argument names, and block type signatures identical between both repos so .sb3 projects are interoperable.
• Register the extension under extensionId: 'server' in the VM's extension manager, matching the id already declared in file:src/lib/libraries/extensions/index.jsx.

Synchronisation policy: Any time LibreKitten merges a change to its server extension blocks, a corresponding PR must be opened against OmniBlocks/scratch-vm to apply the same diff. This should be documented in the OmniBlocks CONTRIBUTING.md.

---

2. Keep the GUI extension entry accurate

In file:src/lib/libraries/extensions/index.jsx, the existing entry:

{
    name: 'Web Server',
    extensionId: 'server',
    collaborator: 'LibreKitten',
    iconURL: serverIcon,
    description: <FormattedMessage id="omni.extension.server.description" ... />,
    tags: ['ob'],
    featured: true
}

• Add incompatibleWithScratch: true (already used by other extensions in the same file) to clearly mark this extension as non-standard Scratch.
• Add docsURI pointing to a shared documentation page (can be https://librekitten.org/ or a future joint docs URL) so users are directed to the same reference from both editors.
• If LibreKitten introduces a distinct inset icon, add insetIconURL importing from ./server/server-small.svg (create the asset alongside the existing file:src/lib/libraries/extensions/server/server.svg).

---

3. Align the platform mismatch detection

The VM emits PLATFORM_MISMATCH when a project saved with one mod is opened in another. To handle Web Server projects gracefully:

• In OmniBlocks/scratch-vm, when serialising/deserialising projects that use the server extension, embed a platform metadata field recognisable to both mods (e.g., { name: 'Web Server Extension', url: 'https://librekitten.org/' }).
• In file:src/lib/vm-listener-hoc.jsx, the existing onPlatformMismatch handler already dispatches openUnknownPlatformModal. No GUI change is needed here—the VM-level metadata is sufficient.

---

4. Add a serverMode flag to the Redux state

In file:src/reducers/tw.js:

• Add a new constant SET_SERVER_MODE = 'tw/SET_SERVER_MODE'.
• Add serverMode: false to initialState.
• Add a case SET_SERVER_MODE branch that sets serverMode.
• Export a setServerMode(serverMode) action creator alongside the existing exports.

This flag allows the GUI to conditionally render server-specific UI (e.g., a port indicator or a "Server is running" badge) without polluting unrelated code paths.

---

5. Add a server status badge component

Following the same pattern as file:src/components/tw-cloud-variable-badge/ (which also shows runtime connection status):

• Create src/components/ob-server-badge/server-badge.jsx – a presentational component that receives serverMode, port, and onToggleServer as props and renders a small status indicator.
• Create src/containers/ob-server-badge.jsx – connects to state.scratchGui.tw.serverMode via mapStateToProps and dispatches setServerMode via mapDispatchToProps.
• Add a CSS module src/components/ob-server-badge/server-badge.css styled consistently with file:src/components/tw-cloud-variable-badge/cloud-variable-badge.css.

The container should be rendered inside file:src/components/gui/gui.jsx in the same area as the cloud variable badge, guarded by props.serverMode.

---

6. Sequence of GUI ↔ VM interaction

sequenceDiagram
    participant User
    participant GUI (ob-server-badge container)
    participant Redux (tw reducer)
    participant VM (scratch3_server extension)

    User->>GUI (ob-server-badge container): Loads project with 'server' extension
    VM (scratch3_server extension)->>Redux (tw reducer): dispatch setServerMode(true) via vm-listener-hoc
    Redux (tw reducer)-->>GUI (ob-server-badge container): serverMode = true
    GUI (ob-server-badge container)-->>User: Renders server status badge

    User->>GUI (ob-server-badge container): Clicks "Stop server"
    GUI (ob-server-badge container)->>Redux (tw reducer): dispatch setServerMode(false)
    Redux (tw reducer)->>VM (scratch3_server extension): vm.postIOData('server', { running: false })
    VM (scratch3_server extension)-->>User: Server stops

Loading

---

7. Document the sharing contract

Add a section to CONTRIBUTING.md and/or DEVLOGS.md describing:

• The server extension block opcodes are frozen between OmniBlocks and LibreKitten — any opcode addition/removal must be coordinated with a cross-repo PR.
• The platform field embedded by the VM must remain consistent so the PLATFORM_MISMATCH dialog in file:src/components/tw-unknown-platform-modal/unknown-platform-modal.jsx shows meaningful information to users who open a LibreKitten server project in OmniBlocks or vice versa.

Import In IDE

🤖 Prompt for AI Agents

## Observations

OmniBlocks already registers a `'Web Server'` extension (extensionId `'server'`, collaborator `'LibreKitten'`) in `file:src/lib/libraries/extensions/index.jsx`. The actual server-side block implementation lives in the `scratch-vm` dependency (`github:OmniBlocks/scratch-vm#develop`). LibreKitten's server runtime is implemented in its own VM fork under `packages/vm/src/server/`. The existing `PLATFORM_MISMATCH` event pipeline (`file:src/lib/vm-listener-hoc.jsx` → `file:src/reducers/tw.js` → `file:src/containers/tw-unknown-platform-modal.jsx`) already guards against cross-mod project incompatibilities.

## Approach

The cleanest way to share the Web Server extension implementation between the two mods is to make OmniBlocks's `scratch-vm` consume the canonical server extension blocks from LibreKitten's upstream VM package rather than maintaining a fork of them. On the GUI side, the extension entry, its icon, and any UI helpers are kept in sync through clearly separated, LibreKitten-attributed files. This avoids duplicating logic and keeps feature parity automatic when LibreKitten ships updates.

---

## Implementation Plan

### 1. Establish the canonical server extension source

In the `OmniBlocks/scratch-vm` repository (the dependency declared in `file:package.json` as `"scratch-vm": "github:OmniBlocks/scratch-vm#develop"`):

- Create a `src/extensions/scratch3_server/` directory mirroring LibreKitten's server extension structure (`packages/vm/src/extensions/scratch3_server/` from the LibreKitten repo).
- The extension class (e.g., `Scratch3ServerBlocks`) must implement the same `getInfo()` block definitions, HTTP request/response hat blocks, routing blocks, and response-sending blocks that LibreKitten exposes—keeping opcodes, argument names, and block type signatures identical between both repos so `.sb3` projects are interoperable.
- Register the extension under `extensionId: 'server'` in the VM's extension manager, matching the id already declared in `file:src/lib/libraries/extensions/index.jsx`.

> **Synchronisation policy:** Any time LibreKitten merges a change to its server extension blocks, a corresponding PR must be opened against `OmniBlocks/scratch-vm` to apply the same diff. This should be documented in the OmniBlocks `CONTRIBUTING.md`.

---

### 2. Keep the GUI extension entry accurate

In `file:src/lib/libraries/extensions/index.jsx`, the existing entry:

```
{
    name: 'Web Server',
    extensionId: 'server',
    collaborator: 'LibreKitten',
    iconURL: serverIcon,
    description: <FormattedMessage id="omni.extension.server.description" ... />,
    tags: ['ob'],
    featured: true
}
```

- Add `incompatibleWithScratch: true` (already used by other extensions in the same file) to clearly mark this extension as non-standard Scratch.
- Add `docsURI` pointing to a shared documentation page (can be `https://librekitten.org/` or a future joint docs URL) so users are directed to the same reference from both editors.
- If LibreKitten introduces a distinct inset icon, add `insetIconURL` importing from `./server/server-small.svg` (create the asset alongside the existing `file:src/lib/libraries/extensions/server/server.svg`).

---

### 3. Align the platform mismatch detection

The VM emits `PLATFORM_MISMATCH` when a project saved with one mod is opened in another. To handle Web Server projects gracefully:

- In `OmniBlocks/scratch-vm`, when serialising/deserialising projects that use the `server` extension, embed a `platform` metadata field recognisable to both mods (e.g., `{ name: 'Web Server Extension', url: 'https://librekitten.org/' }`).
- In `file:src/lib/vm-listener-hoc.jsx`, the existing `onPlatformMismatch` handler already dispatches `openUnknownPlatformModal`. No GUI change is needed here—the VM-level metadata is sufficient.

---

### 4. Add a `serverMode` flag to the Redux state

In `file:src/reducers/tw.js`:

- Add a new constant `SET_SERVER_MODE = 'tw/SET_SERVER_MODE'`.
- Add `serverMode: false` to `initialState`.
- Add a `case SET_SERVER_MODE` branch that sets `serverMode`.
- Export a `setServerMode(serverMode)` action creator alongside the existing exports.

This flag allows the GUI to conditionally render server-specific UI (e.g., a port indicator or a "Server is running" badge) without polluting unrelated code paths.

---

### 5. Add a server status badge component

Following the same pattern as `file:src/components/tw-cloud-variable-badge/` (which also shows runtime connection status):

- Create `src/components/ob-server-badge/server-badge.jsx` – a presentational component that receives `serverMode`, `port`, and `onToggleServer` as props and renders a small status indicator.
- Create `src/containers/ob-server-badge.jsx` – connects to `state.scratchGui.tw.serverMode` via `mapStateToProps` and dispatches `setServerMode` via `mapDispatchToProps`.
- Add a CSS module `src/components/ob-server-badge/server-badge.css` styled consistently with `file:src/components/tw-cloud-variable-badge/cloud-variable-badge.css`.

The container should be rendered inside `file:src/components/gui/gui.jsx` in the same area as the cloud variable badge, guarded by `props.serverMode`.

---

### 6. Sequence of GUI ↔ VM interaction

```mermaid
sequenceDiagram
    participant User
    participant GUI (ob-server-badge container)
    participant Redux (tw reducer)
    participant VM (scratch3_server extension)

    User->>GUI (ob-server-badge container): Loads project with 'server' extension
    VM (scratch3_server extension)->>Redux (tw reducer): dispatch setServerMode(true) via vm-listener-hoc
    Redux (tw reducer)-->>GUI (ob-server-badge container): serverMode = true
    GUI (ob-server-badge container)-->>User: Renders server status badge

    User->>GUI (ob-server-badge container): Clicks "Stop server"
    GUI (ob-server-badge container)->>Redux (tw reducer): dispatch setServerMode(false)
    Redux (tw reducer)->>VM (scratch3_server extension): vm.postIOData('server', { running: false })
    VM (scratch3_server extension)-->>User: Server stops
```

---

### 7. Document the sharing contract

Add a section to `CONTRIBUTING.md` and/or `DEVLOGS.md` describing:

- The server extension block opcodes are **frozen** between OmniBlocks and LibreKitten — any opcode addition/removal must be coordinated with a cross-repo PR.
- The `platform` field embedded by the VM must remain consistent so the `PLATFORM_MISMATCH` dialog in `file:src/components/tw-unknown-platform-modal/unknown-platform-modal.jsx` shows meaningful information to users who open a LibreKitten server project in OmniBlocks or vice versa.

---

Execution Information

Branch: main
Commit: 4e972a5

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[github-actions]

Hi @ampelectrecuted! Thanks for opening this issue.

It seems like you're suggesting the idea of implementation sharing for web server features between OmniBlocks and LibreKitten to maintain consistency. This could potentially streamline development and ensure both mods have a similar approach to handling web servers. However, it’s unclear how this implementation would be structured or the specific challenges you foresee in achieving this. Could you please clarify or expand on the approach you’re envisioning?

Also, since this idea was previously discussed in the linked discussion, it might be helpful to bring more context or outcomes from that conversation into this issue. Looking forward to your thoughts!

[github-actions]

🎭 Issue Poem

In a realm of code where cats do roam,
SomeCat yearned for a shared web home.
With LibreKitten's charm and Omni's might,
Why not merge features, make coding bright?

So let’s weave our webs, both strong and neat,
A tapestry of code, where brilliance meets.
Together we’ll soar, with laughter and cheer,
In this playful project, let’s shift into gear! 🎉

---

Generated with ❤️ by the OmniBlocks Poetry Bot