<?xml version="1.0" encoding="UTF-8"?>
<protocol name="cosmic_surface_embed_v1">
<copyright><![CDATA[
SPDX-FileCopyrightText: 2026 Playtron
SPDX-License-Identifier: GPL-3.0-only
]]></copyright>
<description summary="embed foreign toplevel surfaces">
This protocol allows a client to embed foreign toplevel windows within
their own surface. The embedded surface will be rendered at a specified
position within the parent surface, and input events will be routed
to the embedded surface when the pointer is within the embed region.
This enables applications like chat assistants to display interactive
embedded views of other applications (calendars, web browsers, PDF viewers)
alongside their own UI.
</description>
<interface name="zcosmic_surface_embed_manager_v1" version="1">
<description summary="manager for surface embedding">
This interface is the entry point for creating embedded surface views.
A client can use this to embed foreign toplevel windows within their
own surface hierarchy.
</description>
<request name="destroy" type="destructor">
<description summary="destroy the manager">
Destroy the manager object. This does not affect any existing
embedded surface objects.
</description>
</request>
<request name="embed_toplevel">
<description summary="embed a foreign toplevel into a surface">
Create an embedded surface view for a foreign toplevel window.
The toplevel will be rendered within the specified parent surface
at the geometry set via the embedded surface interface.
The parent surface must belong to the requesting client.
The toplevel_id is the identifier from the toplevel-info protocol
that identifies which toplevel to embed.
</description>
<arg name="id" type="new_id" interface="zcosmic_embedded_surface_v1"/>
<arg name="parent" type="object" interface="wl_surface"
summary="the surface to embed into"/>
<arg name="toplevel_id" type="string"
summary="the identifier of the toplevel to embed"/>
</request>
<request name="embed_toplevel_by_pid">
<description summary="embed a foreign toplevel by process ID">
Create an embedded surface view for a foreign toplevel window
identified by its process ID. This is useful when the parent
application spawns a child process and wants to embed its window
without needing to discover it via the toplevel-list protocol.
The compositor will monitor for new toplevels from the specified
PID. When a matching toplevel appears, it will be embedded.
If no toplevel from the specified PID appears within a reasonable
timeout (e.g. 30 seconds), the embedded surface object becomes inert
and a 'closed' event is sent.
The parent surface must belong to the requesting client.
The pid should be a child process of the requesting client.
</description>
<arg name="id" type="new_id" interface="zcosmic_embedded_surface_v1"/>
<arg name="parent" type="object" interface="wl_surface"
summary="the surface to embed into"/>
<arg name="pid" type="uint"
summary="the process ID of the application to embed"/>
<arg name="app_id" type="string"
summary="expected app_id for verification (optional, can be empty)"/>
</request>
</interface>
<interface name="zcosmic_embedded_surface_v1" version="1">
<description summary="an embedded foreign surface">
This interface represents an embedded view of a foreign toplevel
within a parent surface. The client can configure the position,
size, and interactivity of the embedded view.
Input events (pointer, keyboard, touch) within the embed region
will be automatically routed to the embedded toplevel when
interactive mode is enabled.
</description>
<enum name="error">
<entry name="invalid_geometry" value="0"
summary="geometry values are invalid"/>
<entry name="toplevel_destroyed" value="1"
summary="the embedded toplevel was destroyed"/>
</enum>
<request name="destroy" type="destructor">
<description summary="destroy the embedded surface">
Destroy the embedded surface object. The embedded toplevel will
no longer be rendered within the parent surface, and input
routing will stop.
</description>
</request>
<enum name="anchor" bitfield="true">
<description summary="anchor edges for positioning">
These flags specify which edges of the parent surface the embedded
surface should be anchored to. The compositor will automatically
calculate the position based on the anchor edges and margins.
</description>
<entry name="none" value="0" summary="no anchoring, use absolute position"/>
<entry name="top" value="1" summary="anchor to top edge"/>
<entry name="bottom" value="2" summary="anchor to bottom edge"/>
<entry name="left" value="4" summary="anchor to left edge"/>
<entry name="right" value="8" summary="anchor to right edge"/>
</enum>
<request name="set_anchor">
<description summary="set anchor-based positioning">
Set the embedded surface position using anchor-based positioning.
This is an alternative to set_geometry that allows the compositor
to automatically calculate the position based on parent size.
The anchor parameter specifies which edges to anchor to. Margins
specify the distance from each edge. Width and height specify the
size of the embed region.
For example, to anchor to top-right with margins:
- anchor = top | right
- margin_top = distance from parent top
- margin_right = distance from parent right edge
- width/height = size of embed region
If both opposing edges are anchored (e.g., left and right), the
embed will stretch between them minus the margins.
This request overrides any previous set_geometry call.
</description>
<arg name="anchor" type="uint" enum="anchor" summary="anchor edge flags"/>
<arg name="margin_top" type="int" summary="margin from top edge"/>
<arg name="margin_right" type="int" summary="margin from right edge"/>
<arg name="margin_bottom" type="int" summary="margin from bottom edge"/>
<arg name="margin_left" type="int" summary="margin from left edge"/>
<arg name="width" type="int" summary="width of embed region (0 to stretch)"/>
<arg name="height" type="int" summary="height of embed region (0 to stretch)"/>
</request>
<request name="set_geometry">
<description summary="set the embed region geometry">
Set the position and size of the embedded surface within the
parent surface. The embedded toplevel will be scaled to fit
this region.
The geometry is in surface-local coordinates of the parent.
Width and height must be positive.
This request uses absolute positioning. For anchor-based positioning
that automatically adjusts to parent size, use set_anchor instead.
</description>
<arg name="x" type="int" summary="x position in parent surface"/>
<arg name="y" type="int" summary="y position in parent surface"/>
<arg name="width" type="int" summary="width of embed region"/>
<arg name="height" type="int" summary="height of embed region"/>
</request>
<request name="set_corner_radius">
<description summary="set the corner radius for the embedded surface">
Set the corner radius for clipping the embedded surface. This allows
the parent to specify rounded corners that match its own UI.
Each corner can have a different radius. Values are in logical pixels.
A value of 0 means no rounding for that corner.
Default is 0 for all corners (square corners).
</description>
<arg name="top_left" type="uint" summary="top-left corner radius"/>
<arg name="top_right" type="uint" summary="top-right corner radius"/>
<arg name="bottom_right" type="uint" summary="bottom-right corner radius"/>
<arg name="bottom_left" type="uint" summary="bottom-left corner radius"/>
</request>
<request name="set_interactive">
<description summary="enable or disable input routing">
When interactive is non-zero, pointer, keyboard, and touch events
within the embed region will be routed to the embedded toplevel.
The embedded window will receive focus when clicked.
When interactive is zero, the embedded surface is display-only
and all input goes to the parent surface.
Default is non-interactive (0).
</description>
<arg name="interactive" type="uint"
summary="non-zero to enable input routing"/>
</request>
<request name="set_render_mode">
<description summary="set how the embedded surface is rendered">
Configure the rendering mode for the embedded surface.
Mode 0 (live): The embedded surface is rendered live with
real-time updates. This uses compositor-side rendering.
Mode 1 (screencopy): The embedded surface is captured via
screencopy and sent to the client as frames. This allows
the client to apply effects or transformations.
Default is live (0).
</description>
<arg name="mode" type="uint" summary="0 for live, 1 for screencopy"/>
</request>
<request name="commit">
<description summary="apply pending changes">
Apply all pending geometry and mode changes. Changes are
double-buffered and only take effect after commit.
</description>
</request>
<event name="configure">
<description summary="embedded toplevel configuration changed">
Sent when the embedded toplevel's preferred size changes.
The client may want to adjust the embed geometry to match.
</description>
<arg name="width" type="int" summary="preferred width"/>
<arg name="height" type="int" summary="preferred height"/>
</event>
<event name="frame">
<description summary="new frame available (screencopy mode)">
In screencopy mode, sent when a new frame has been captured
and is ready to be displayed. The client should request the
frame data via the screencopy interface.
In live mode, this event is not sent.
</description>
</event>
<event name="closed">
<description summary="embedded toplevel was closed">
The embedded toplevel was closed by the user or application.
The embedded surface object becomes inert after this event.
The client should destroy this object.
</description>
</event>
<event name="entered">
<description summary="pointer entered embed region">
Sent when the pointer enters the embed region and input
routing to the embedded toplevel begins.
</description>
</event>
<event name="left">
<description summary="pointer left embed region">
Sent when the pointer leaves the embed region and input
routing to the embedded toplevel stops.
</description>
</event>
</interface>
</protocol>