[Proposal] Additive non-overlapping right-side panel extension for plugins

[LH-kevin]

Summary

Plugins currently have two supported surfaces that are relevant to right-side panels:

• shell.overlay, which is additive but rendered as a floating overlay
• details, which participates in the real layout but is a single-occupant slot used by the first-party tool-details panel

Neither currently provides a generic additive, non-overlapping, width-reserving third-party panel that can sit beside the conversation without replacing native Harness UI.

This is a generic plugin-extension capability request rather than a request for a plugin-specific API.

Problem

shell.overlay

shell.overlay is:

• kind: 'list'
• scope: 'root'
• additive
• safe for third-party registration

However, it is rendered inside the AppFrame's floating overlay layer.

It does not participate in the shell's grid columns, reserves no layout width, and does not cause the center/conversation column to reflow.

As a result, a right-positioned plugin panel registered through shell.overlay necessarily covers part of the conversation.

details

The details surface has the opposite properties:

• it is a real AppFrame layout column
• it reserves width
• opening it narrows the conversation
• it is controlled through ctx.layout.openDetails() / closeDetails()

But details is:

• kind: 'single'
• scope: 'session'

and is already occupied by the first-party conversation DetailsPanel / tool-details UI.

A third-party plugin registering its own component into details therefore replaces the native tool-details occupant rather than coexisting with it.

So today a plugin effectively has two choices:

1. use shell.overlay and cover part of the conversation; or
2. use details and displace the first-party details panel.

Neither is a good general extension contract for:

show a plugin panel beside the conversation while preserving native Harness functionality.

Source evidence

Relevant areas in the current source include:

• packages/client/ui-layout/src/client/index.ts

  • declares details as a session-scoped single slot
  • declares shell.overlay as a root-scoped list slot

• packages/client/ui-layout/src/client/AppFrame.tsx

  • renders the main grid as sidebar / center / details
  • renders shell.overlay in the floating overlay layer
  • uses computeColumns(...) for layout width allocation

• packages/client/ui-layout/src/client/columns.ts

  • contains the column sizing/reflow logic

• packages/client/ui-layout/src/client/stores.ts

• packages/client/ui-layout/src/client/service.ts

  • contain layout state and openDetails() / closeDetails()

• the first-party conversation UI registers its own DetailsPanel into the details surface

This appears to be an extension-contract limitation rather than a CSS issue in an individual plugin.

Required properties of a generic plugin panel contract

A general solution would ideally support:

• third-party registration
• additive behavior
• non-overlapping layout
• real width reservation
• center/conversation reflow
• explicit open/close lifecycle
• automatic cleanup when a plugin unloads
• no displacement of the native tool-details panel
• deterministic behavior when multiple plugins register panels
• defined responsive behavior
• a clear coexistence contract with the existing details column

Design alternatives

I do not think the current source makes one design uniquely correct, so I would prefer maintainer guidance before proposing an implementation.

Option A — Make details multi-tenant

Change details from a single occupant into some form of container, such as a list, tab set, or composed panel area.

The first-party tool-details panel would become one entry and plugins could add others.

Advantages

• reuses the existing details geometry
• reuses existing width allocation and conversation reflow
• reuses the current details open/close model

Trade-offs

• changes an existing single slot semantic
• directly affects first-party DetailsPanel
• requires a clear arbitration/tab/selection model
• has greater compatibility risk

Option B — Add a separate plugin right-rail column

Introduce a new additive right-side layout surface, conceptually something like:

'shell.right-rail': {
  kind: 'list',
  scope: /* to be decided */,
  owner: RightRailOwnerProps,
}

The exact name and shape are only illustrative.

This rail would reserve real AppFrame width while leaving the existing native details column unchanged.

Advantages

• additive
• does not alter existing details semantics
• does not displace tool-details
• gives plugin panels a clearly separate responsibility

Trade-offs

• AppFrame and computeColumns would need to support an additional layout region
• width ownership needs to be defined
• responsive/collapse behavior needs a new contract
• coexistence with the native details column needs to be specified

Option C — Generalized reservable panel instances

Instead of defining one additional right rail, allow plugins to declare panel instances that participate in shell layout and reserve space.

Advantages

• most general
• could support future layout extensions beyond one right-side panel

Trade-offs

• significantly larger API and layout-model change
• requires stronger arbitration and geometry rules
• may be broader than what Harness currently needs

Questions for maintainers

I would appreciate guidance on the intended direction, particularly:

1. Should third-party right-side panels reuse the existing details concept, or remain separate from it?
2. Is one third-party right rail sufficient, or should multiple plugin panels be supported?
3. If multiple plugins register panels, should the UI use tabs, priority, a single active winner, or another model?
4. Should the native details panel and a plugin right rail ever be visible at the same time?
5. On smaller viewports, which region should collapse first?
6. Who should own the preferred panel width: the plugin, the layout service, or the shell?
7. Should plugin panel state be session-scoped or root-scoped?
8. Should the selected/open plugin panel be persisted?
9. Would you prefer a dedicated additive right-rail contract, or a more general redesign of the existing details surface?

This is intended as a design discussion rather than a prescriptive implementation request.

Backward compatibility

Ideally, any extension would preserve the current behavior when no third-party panel is registered:

• existing details behavior remains unchanged
• native tool-details remains available
• existing shell.overlay semantics remain unchanged
• plugins that currently use existing slots continue to work
• no layout difference is introduced when the new extension is unused

Practical validation

This limitation was encountered while building a real third-party Harness plugin.

We tested both currently supported approaches:

• registering the plugin panel through shell.overlay works and is additive, but the panel covers part of the conversation because the overlay does not participate in layout
• registering the panel through details produces the desired real reflow, but replaces the native tool-details occupant

We rejected the second approach because a third-party plugin should not gain its UI by removing an existing first-party Harness capability.

That experiment was not pushed upstream; it was only used to validate the current extension behavior.

I couldn't find an existing public discussion, issue, or PR covering this. If this is already being discussed elsewhere or internally, please point me to the relevant direction.

[LH-kevin]

Hi @imccyu — sorry for the ping. This is currently blocking a real third-party plugin use case that needs an additive right-side panel which participates in AppFrame reflow without replacing the shipped details occupant. Since you've recently worked on the client slot/layout architecture, I'd appreciate any guidance on the intended extension direction here. Thanks!