@matterfact/embed 0.7.0 → 0.8.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 = 2;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -143,6 +143,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';
@@ -183,6 +190,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 +269,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.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.setExpanded';
-    expanded: boolean;
+    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 +345,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';
 }
@@ -386,7 +442,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 +478,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 +526,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 +545,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

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 = 2;
 /** Every message is namespaced so we never collide with the host page's own postMessage traffic. */
 declare const CHANNEL = "mf-embed";
 /**
@@ -143,6 +143,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';
@@ -183,6 +190,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 +269,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.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.setExpanded';
-    expanded: boolean;
+    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 +345,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';
 }
@@ -386,7 +442,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 +478,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 +526,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 +545,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