@matterfact/embed 0.7.0 → 0.9.0

package/dist/index.d.cts

@@ -18,7 +18,7 @@
  *    shapes are right, "deeper integration" is a transport swap (postMessage ->
  *    direct call), not a rewrite. So model the DOMAIN here, not the plumbing.
  */
-declare const PROTOCOL_VERSION = 1;
+declare const PROTOCOL_VERSION = 3;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -58,6 +58,43 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
 /** A co-embedded artifact's read-only capability, for the backend to materialize its
  *  data. Backend-only — never rendered. `token` is the artifact's own embed token. */
 interface ArtifactGrant {
@@ -143,6 +180,13 @@ interface HostTool {
      * requires the user to confirm, every time — see the note on ToolCall.
      */
     readOnly?: boolean;
+    /**
+     * The tiered confirm policy, set by the host (e.g. `window.matterfact.hoist.actions`):
+     * `'required'` ⇒ the widget must show a confirm card and get the user's approval
+     * before every call; `'auto'` ⇒ it may call without asking. Absent for a tool that
+     * predates this policy (treat as `'required'` — the safer default).
+     */
+    confirm?: 'auto' | 'required';
 }
 type HostToWidget = {
     type: 'host.ready';
@@ -167,6 +211,17 @@ type HostToWidget = {
 } | {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
+}
+/**
+ * The annotated site map — the app's routes with the host's content
+ * classification. Sent on mount and re-sent on navigation (a virtualized SPA can
+ * change what's routable). Distinct from the per-page `host.context`: this is the
+ * whole app's structure, so the agent can reason about and navigate toward MF
+ * content the user isn't currently looking at.
+ */
+ | {
+    type: 'host.sitemap';
+    sitemap: SiteMapEntry[];
 } | {
     type: 'host.tools';
     tools: HostTool[];
@@ -183,6 +238,23 @@ type HostToWidget = {
 } | {
     type: 'host.theme';
     mode: 'light' | 'dark';
+}
+/**
+ * Where the widget currently IS. Sent on mount and after anything that moves it
+ * (drag, snap, mode change, viewport resize).
+ *
+ * The widget cannot work this out for itself — it can't see the viewport, and the
+ * loader owns the box. Without it the widget renders its launcher against a stale
+ * guess: a launcher dragged to the left edge kept drawing its circle bottom-RIGHT
+ * inside a left-anchored box, so the circle jumped as soon as the box grew for the
+ * hover pill. `growth` is the direction the pill/menu/panel must open (toward the
+ * viewport centre); `mode` decides whether the launcher is a circle or an edge tab.
+ */
+ | {
+    type: 'host.geometry';
+    mode: 'float' | 'dock';
+    dockSide: 'left' | 'right';
+    growth: 'tl' | 'tr' | 'bl' | 'br';
 };
 /**
  * The agent asking the host to do something.
@@ -245,14 +317,57 @@ type WidgetToHost = {
     height: number;
 }
 /**
- * Maximize / restore. Expanded makes the iframe fill the viewport (with a small
- * margin) so the composer's `/` picker, mention previews, and the transcript have
- * room the corner popup can't give them. The loader owns the iframe size, so only
- * it can do this — `widget.resize` (height-only) can't widen the popup.
+ * Dock / undock the open panel.
+ *
+ * Docked is a FULL-HEIGHT SIDE PANEL on the launcher's own side — left corners dock
+ * to the left edge, right corners to the right, unless `setDockSide` overrides it.
+ * This replaces the old `setExpanded`, which was hardcoded to the right edge and so
+ * threw the panel across the screen whenever the launcher sat on the left.
+ *
+ * The loader owns the box, so only it can do this — `widget.resize` (height-only)
+ * can neither widen the panel nor move it to an edge.
+ */
+ | {
+    type: 'widget.setMode';
+    mode: 'float' | 'dock';
+}
+/** Which edge the tab and its panel live on. */
+ | {
+    type: 'widget.setDockSide';
+    side: 'left' | 'right';
+}
+/** Place the FLOATING launcher at a specific corner (the menu's snap picker). */
+ | {
+    type: 'widget.snapCorner';
+    corner: 'tl' | 'tr' | 'bl' | 'br';
+}
+/**
+ * Resize the COLLAPSED launcher's host box so the widget can paint outside the 56px
+ * circle — the hover pill (`{w:180,h:56}`) or the context menu (its own box). The
+ * iframe clips to the host box, so anything beside the circle is invisible until the
+ * host makes room. `{w:56,h:56}` returns to the bare circle. Ignored while open.
  */
  | {
-    type: 'widget.setExpanded';
-    expanded: boolean;
+    type: 'widget.setLauncherRegion';
+    w: number;
+    h: number;
+}
+/**
+ * User resize of the floating panel, via the grip on its inner corner.
+ *
+ * Same contract as the launcher drag below, and for the same reason: the press is
+ * captured by the iframe, so the host cannot see the moves. The widget tracks the
+ * gesture and sends SCREEN-coordinate deltas; the loader owns the sizing, the
+ * per-corner sign of the delta, and the clamp.
+ */
+ | {
+    type: 'widget.resizeStart';
+} | {
+    type: 'widget.resizeMove';
+    dx: number;
+    dy: number;
+} | {
+    type: 'widget.resizeEnd';
 }
 /**
  * Launcher drag. The widget tracks the gesture; the host only moves the element.
@@ -278,18 +393,7 @@ type WidgetToHost = {
 } | {
     type: 'widget.dragEnd';
 }
-/**
- * Grow/shrink the iframe to fit the launcher's context menu. The collapsed launcher is
- * only ~64px tall, so a menu rendered inside it would be clipped by the iframe's own
- * bounds — the host has to make room before it can be seen. `widget.resize` can't do
- * this: it's height-only AND ignored while closed.
- */
- | {
-    type: 'widget.setMenu';
-    open: boolean;
-    height: number;
-}
-/** Put the launcher back in the default corner and forget the dragged position. */
+/** Put the launcher back in the default corner and forget the saved size/dock. */
  | {
     type: 'widget.resetPos';
 }
@@ -300,6 +404,16 @@ type WidgetToHost = {
 /** The widget has no session; the host must run the hosted-login popup. */
  | {
     type: 'widget.needsAuth';
+}
+/**
+ * Deeplink the host to one of its OWN routes — the "open on page" control on a
+ * co-embedded document's side-panel viewer. The widget is a cross-origin iframe and
+ * can't navigate the top window itself, so it asks the loader, which resolves the
+ * href against the host location and refuses anything off the host's own origin.
+ */
+ | {
+    type: 'widget.navigate';
+    href: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -386,7 +500,7 @@ interface LoaderConfig {
      * own side panel, tool drawer or tab and wants the agent to live there.
      *
      * This inverts who owns the chrome. In corner mode the widget owns everything: it draws
-     * its own launcher and it tells us how big to be (setOpen/setExpanded/resize). Inside
+     * its own launcher and it tells us how big to be (setOpen/setDocked/resize). Inside
      * someone else's panel, both are theirs — a widget that resized its host's drawer, or
      * drew a second floating bubble inside it, is just broken. So here we fill the
      * container, ignore the size messages, and the widget skips the launcher and renders
@@ -422,11 +536,31 @@ declare class EmbedHost {
     private queue;
     private ready;
     private open;
-    private expanded;
-    /** Null until the user drags; then it pins the corner offset and survives reloads. */
-    private pos;
-    /** Where the launcher sat when the current drag began; deltas are applied to this. */
-    private dragBase;
+    /** The persisted box: launcher corner, float size, dock state/side/width. */
+    private geo;
+    /** Float size at resizeStart; resizeMove deltas apply against it (they're cumulative). */
+    private resizeBase;
+    /** Docked width at resizeStart — the docked panel resizes in one axis only. */
+    private dockBase;
+    /** The widget's logical anchor when the drag began, and where it is now. Deltas arrive
+     *  cumulative from the press, so the current spot is simply origin + delta — no need to
+     *  read the box back, which stops being the thing we're moving the moment it docks. */
+    private dragFrom;
+    private dragAt;
+    /** The painted box when the drag began — the edge test measures what you can SEE
+     *  touching the screen edge, which is not the anchor once the panel is open. */
+    private dragBox;
+    /** Growth direction frozen for the drag — see floatChrome's `growth` param. */
+    private dragGrowth;
+    /**
+     * Has this drag been clear of the dock band yet?
+     *
+     * The resting position is INSIDE the band — a corner-anchored widget sits MARGIN
+     * (20px) from the edge, well within EDGE_DOCK (64px) — so without this, picking one
+     * up docked it instantly, before it had moved anywhere. Docking now requires
+     * ENTERING the band rather than merely starting in it.
+     */
+    private dragLeftBand;
     /** Loaded on first open. Holds everything that touches the customer's DOM. */
     private context;
     /** The host element; kept so `destroy()` can remove it (React lifecycle). */
@@ -450,6 +584,13 @@ declare class EmbedHost {
      * on it has plenty of frames.
      */
     private onMessage;
+    /**
+     * Test seam. The shadow root is CLOSED, so a test cannot reach the iframe to forge a
+     * source-valid MessageEvent — this routes a message through the identical logic
+     * without weakening the origin/source checks above, which stay the only real door.
+     */
+    __testHandle(msg: WidgetToHost): void;
+    private handle;
     /**
      * Own a drag for its lifetime.
      *
@@ -462,12 +603,31 @@ declare class EmbedHost {
      * We are the dumb half on purpose — see `widget.dragMove` in the protocol for why the
      * widget has to own the gesture. All we do is take a delta and place the element.
      */
-    private cornerOffset;
-    private dragTo;
-    /** Reset to the default corner (a menu action — the drag is otherwise sticky). */
-    private resetPos;
-    private readPos;
-    private writePos;
+    /** Write a box onto the host element and stamp the mode the shadow CSS keys off. */
+    private applyBox;
+    /** Re-apply the box for whatever state we're in: collapsed launcher, float, or dock. */
+    /**
+     * The growth direction to use RIGHT NOW — frozen while a drag is in flight.
+     *
+     * Every consumer has to agree on this, which is the bug that made the widget
+     * flip-flop under small movements near the viewport centre: the box was frozen but
+     * `host.geometry` still published a freshly-derived growth, so the WIDGET kept
+     * swapping which corner it drew against (and it animates that), twitching back and
+     * forth while the loader held perfectly still.
+     */
+    private growthNow;
+    private place;
+    /**
+     * Tell the widget where it is. It can't see the viewport and doesn't own the box, so
+     * without this it draws its launcher against a stale guess — which is what made the
+     * circle jump when the launcher sat on the left (see `host.geometry` in the protocol).
+     */
+    private publishGeometry;
+    /** The theme to publish: an explicit data-theme wins, else the OS preference. */
+    private themeMode;
+    private onViewportResize;
+    private readGeometry;
+    private writeGeometry;
     /**
      * Answer `widget.needsAuth`. If a trusted first-party host has an auth-token provider,
      * call it and hand the token straight to the widget via `host.auth` — no popup. The
@@ -501,4 +661,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  *    shapes are right, "deeper integration" is a transport swap (postMessage ->
  *    direct call), not a rewrite. So model the DOMAIN here, not the plumbing.
  */
-declare const PROTOCOL_VERSION = 1;
+declare const PROTOCOL_VERSION = 3;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -58,6 +58,43 @@ interface PageEntity {
     text?: string;
     data?: Record<string, unknown>;
 }
+/**
+ * How a route's content is classified, for the annotated site map.
+ *
+ * The host DECORATES the site map we auto-derive (see `SiteMapEntry`) so the agent
+ * knows which routes carry MATTERFACT content and of what kind — app-wide awareness
+ * it can navigate toward. This is CLASSIFICATION only: no per-instance ids, and never
+ * a capability token. The concrete artifact/document on the CURRENT page still arrives
+ * via `host.context` entities / `host.artifactGrants`, resolved per page.
+ *
+ *  - `mf-artifact`  — a co-embedded matterfact artifact (its slug); the token stays on
+ *                     the live iframe / grant, never here.
+ *  - `mf-document`  — a matterfact document (dossier/report), resolved to an MF_DOC_ID
+ *                     host-side per page.
+ *  - `host-data`    — the host's own data; not a matterfact entity.
+ */
+type ContentClass = {
+    kind: 'mf-artifact';
+    slug: string;
+} | {
+    kind: 'mf-document';
+    doctype: string;
+} | {
+    kind: 'host-data';
+};
+/**
+ * One route in the annotated site map: the path pattern + label we derived, plus the
+ * host's content classification. `current` marks the route the user is on.
+ */
+interface SiteMapEntry {
+    /** Route pattern or path, e.g. '/app/company/:ticker/dossier'. */
+    path: string;
+    /** Human label for the route ('Company Dossier'). */
+    label?: string;
+    /** The host's classification of this route's content, when it annotated it. */
+    content?: ContentClass;
+    current?: boolean;
+}
 /** A co-embedded artifact's read-only capability, for the backend to materialize its
  *  data. Backend-only — never rendered. `token` is the artifact's own embed token. */
 interface ArtifactGrant {
@@ -143,6 +180,13 @@ interface HostTool {
      * requires the user to confirm, every time — see the note on ToolCall.
      */
     readOnly?: boolean;
+    /**
+     * The tiered confirm policy, set by the host (e.g. `window.matterfact.hoist.actions`):
+     * `'required'` ⇒ the widget must show a confirm card and get the user's approval
+     * before every call; `'auto'` ⇒ it may call without asking. Absent for a tool that
+     * predates this policy (treat as `'required'` — the safer default).
+     */
+    confirm?: 'auto' | 'required';
 }
 type HostToWidget = {
     type: 'host.ready';
@@ -167,6 +211,17 @@ type HostToWidget = {
 } | {
     type: 'host.artifactGrants';
     grants: ArtifactGrant[];
+}
+/**
+ * The annotated site map — the app's routes with the host's content
+ * classification. Sent on mount and re-sent on navigation (a virtualized SPA can
+ * change what's routable). Distinct from the per-page `host.context`: this is the
+ * whole app's structure, so the agent can reason about and navigate toward MF
+ * content the user isn't currently looking at.
+ */
+ | {
+    type: 'host.sitemap';
+    sitemap: SiteMapEntry[];
 } | {
     type: 'host.tools';
     tools: HostTool[];
@@ -183,6 +238,23 @@ type HostToWidget = {
 } | {
     type: 'host.theme';
     mode: 'light' | 'dark';
+}
+/**
+ * Where the widget currently IS. Sent on mount and after anything that moves it
+ * (drag, snap, mode change, viewport resize).
+ *
+ * The widget cannot work this out for itself — it can't see the viewport, and the
+ * loader owns the box. Without it the widget renders its launcher against a stale
+ * guess: a launcher dragged to the left edge kept drawing its circle bottom-RIGHT
+ * inside a left-anchored box, so the circle jumped as soon as the box grew for the
+ * hover pill. `growth` is the direction the pill/menu/panel must open (toward the
+ * viewport centre); `mode` decides whether the launcher is a circle or an edge tab.
+ */
+ | {
+    type: 'host.geometry';
+    mode: 'float' | 'dock';
+    dockSide: 'left' | 'right';
+    growth: 'tl' | 'tr' | 'bl' | 'br';
 };
 /**
  * The agent asking the host to do something.
@@ -245,14 +317,57 @@ type WidgetToHost = {
     height: number;
 }
 /**
- * Maximize / restore. Expanded makes the iframe fill the viewport (with a small
- * margin) so the composer's `/` picker, mention previews, and the transcript have
- * room the corner popup can't give them. The loader owns the iframe size, so only
- * it can do this — `widget.resize` (height-only) can't widen the popup.
+ * Dock / undock the open panel.
+ *
+ * Docked is a FULL-HEIGHT SIDE PANEL on the launcher's own side — left corners dock
+ * to the left edge, right corners to the right, unless `setDockSide` overrides it.
+ * This replaces the old `setExpanded`, which was hardcoded to the right edge and so
+ * threw the panel across the screen whenever the launcher sat on the left.
+ *
+ * The loader owns the box, so only it can do this — `widget.resize` (height-only)
+ * can neither widen the panel nor move it to an edge.
+ */
+ | {
+    type: 'widget.setMode';
+    mode: 'float' | 'dock';
+}
+/** Which edge the tab and its panel live on. */
+ | {
+    type: 'widget.setDockSide';
+    side: 'left' | 'right';
+}
+/** Place the FLOATING launcher at a specific corner (the menu's snap picker). */
+ | {
+    type: 'widget.snapCorner';
+    corner: 'tl' | 'tr' | 'bl' | 'br';
+}
+/**
+ * Resize the COLLAPSED launcher's host box so the widget can paint outside the 56px
+ * circle — the hover pill (`{w:180,h:56}`) or the context menu (its own box). The
+ * iframe clips to the host box, so anything beside the circle is invisible until the
+ * host makes room. `{w:56,h:56}` returns to the bare circle. Ignored while open.
  */
  | {
-    type: 'widget.setExpanded';
-    expanded: boolean;
+    type: 'widget.setLauncherRegion';
+    w: number;
+    h: number;
+}
+/**
+ * User resize of the floating panel, via the grip on its inner corner.
+ *
+ * Same contract as the launcher drag below, and for the same reason: the press is
+ * captured by the iframe, so the host cannot see the moves. The widget tracks the
+ * gesture and sends SCREEN-coordinate deltas; the loader owns the sizing, the
+ * per-corner sign of the delta, and the clamp.
+ */
+ | {
+    type: 'widget.resizeStart';
+} | {
+    type: 'widget.resizeMove';
+    dx: number;
+    dy: number;
+} | {
+    type: 'widget.resizeEnd';
 }
 /**
  * Launcher drag. The widget tracks the gesture; the host only moves the element.
@@ -278,18 +393,7 @@ type WidgetToHost = {
 } | {
     type: 'widget.dragEnd';
 }
-/**
- * Grow/shrink the iframe to fit the launcher's context menu. The collapsed launcher is
- * only ~64px tall, so a menu rendered inside it would be clipped by the iframe's own
- * bounds — the host has to make room before it can be seen. `widget.resize` can't do
- * this: it's height-only AND ignored while closed.
- */
- | {
-    type: 'widget.setMenu';
-    open: boolean;
-    height: number;
-}
-/** Put the launcher back in the default corner and forget the dragged position. */
+/** Put the launcher back in the default corner and forget the saved size/dock. */
  | {
     type: 'widget.resetPos';
 }
@@ -300,6 +404,16 @@ type WidgetToHost = {
 /** The widget has no session; the host must run the hosted-login popup. */
  | {
     type: 'widget.needsAuth';
+}
+/**
+ * Deeplink the host to one of its OWN routes — the "open on page" control on a
+ * co-embedded document's side-panel viewer. The widget is a cross-origin iframe and
+ * can't navigate the top window itself, so it asks the loader, which resolves the
+ * href against the host location and refuses anything off the host's own origin.
+ */
+ | {
+    type: 'widget.navigate';
+    href: string;
 };
 /**
  * Everything on the wire is wrapped.
@@ -386,7 +500,7 @@ interface LoaderConfig {
      * own side panel, tool drawer or tab and wants the agent to live there.
      *
      * This inverts who owns the chrome. In corner mode the widget owns everything: it draws
-     * its own launcher and it tells us how big to be (setOpen/setExpanded/resize). Inside
+     * its own launcher and it tells us how big to be (setOpen/setDocked/resize). Inside
      * someone else's panel, both are theirs — a widget that resized its host's drawer, or
      * drew a second floating bubble inside it, is just broken. So here we fill the
      * container, ignore the size messages, and the widget skips the launcher and renders
@@ -422,11 +536,31 @@ declare class EmbedHost {
     private queue;
     private ready;
     private open;
-    private expanded;
-    /** Null until the user drags; then it pins the corner offset and survives reloads. */
-    private pos;
-    /** Where the launcher sat when the current drag began; deltas are applied to this. */
-    private dragBase;
+    /** The persisted box: launcher corner, float size, dock state/side/width. */
+    private geo;
+    /** Float size at resizeStart; resizeMove deltas apply against it (they're cumulative). */
+    private resizeBase;
+    /** Docked width at resizeStart — the docked panel resizes in one axis only. */
+    private dockBase;
+    /** The widget's logical anchor when the drag began, and where it is now. Deltas arrive
+     *  cumulative from the press, so the current spot is simply origin + delta — no need to
+     *  read the box back, which stops being the thing we're moving the moment it docks. */
+    private dragFrom;
+    private dragAt;
+    /** The painted box when the drag began — the edge test measures what you can SEE
+     *  touching the screen edge, which is not the anchor once the panel is open. */
+    private dragBox;
+    /** Growth direction frozen for the drag — see floatChrome's `growth` param. */
+    private dragGrowth;
+    /**
+     * Has this drag been clear of the dock band yet?
+     *
+     * The resting position is INSIDE the band — a corner-anchored widget sits MARGIN
+     * (20px) from the edge, well within EDGE_DOCK (64px) — so without this, picking one
+     * up docked it instantly, before it had moved anywhere. Docking now requires
+     * ENTERING the band rather than merely starting in it.
+     */
+    private dragLeftBand;
     /** Loaded on first open. Holds everything that touches the customer's DOM. */
     private context;
     /** The host element; kept so `destroy()` can remove it (React lifecycle). */
@@ -450,6 +584,13 @@ declare class EmbedHost {
      * on it has plenty of frames.
      */
     private onMessage;
+    /**
+     * Test seam. The shadow root is CLOSED, so a test cannot reach the iframe to forge a
+     * source-valid MessageEvent — this routes a message through the identical logic
+     * without weakening the origin/source checks above, which stay the only real door.
+     */
+    __testHandle(msg: WidgetToHost): void;
+    private handle;
     /**
      * Own a drag for its lifetime.
      *
@@ -462,12 +603,31 @@ declare class EmbedHost {
      * We are the dumb half on purpose — see `widget.dragMove` in the protocol for why the
      * widget has to own the gesture. All we do is take a delta and place the element.
      */
-    private cornerOffset;
-    private dragTo;
-    /** Reset to the default corner (a menu action — the drag is otherwise sticky). */
-    private resetPos;
-    private readPos;
-    private writePos;
+    /** Write a box onto the host element and stamp the mode the shadow CSS keys off. */
+    private applyBox;
+    /** Re-apply the box for whatever state we're in: collapsed launcher, float, or dock. */
+    /**
+     * The growth direction to use RIGHT NOW — frozen while a drag is in flight.
+     *
+     * Every consumer has to agree on this, which is the bug that made the widget
+     * flip-flop under small movements near the viewport centre: the box was frozen but
+     * `host.geometry` still published a freshly-derived growth, so the WIDGET kept
+     * swapping which corner it drew against (and it animates that), twitching back and
+     * forth while the loader held perfectly still.
+     */
+    private growthNow;
+    private place;
+    /**
+     * Tell the widget where it is. It can't see the viewport and doesn't own the box, so
+     * without this it draws its launcher against a stale guess — which is what made the
+     * circle jump when the launcher sat on the left (see `host.geometry` in the protocol).
+     */
+    private publishGeometry;
+    /** The theme to publish: an explicit data-theme wins, else the OS preference. */
+    private themeMode;
+    private onViewportResize;
+    private readGeometry;
+    private writeGeometry;
     /**
      * Answer `widget.needsAuth`. If a trusted first-party host has an auth-token provider,
      * call it and hand the token straight to the widget via `host.auth` — no popup. The
@@ -501,4 +661,4 @@ declare class EmbedHost {
  */
 declare function mount(config: LoaderConfig): EmbedHost;
 
-export { type ActivityEvent, type ArtifactGrant, CHANNEL, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };
+export { type ActivityEvent, type ArtifactGrant, CHANNEL, type ContentClass, type DomSnapshot, type ElementRef, EmbedHost, type Envelope, type FocusContext, type HostToWidget, type HostTool, type LoaderConfig, PROTOCOL_VERSION, type PageContext, type PageEntity, type SiteMapEntry, type ToolCall, type WidgetToHost, envelope, isEnvelope, mount, readConfig };