@particle-academy/agent-integrations 0.46.0 → 0.47.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (96) hide show
  1. package/CHANGELOG.md +835 -0
  2. package/LICENSE +21 -0
  3. package/README.md +44 -3
  4. package/dist/bridges/artboard.d.cts +3 -3
  5. package/dist/bridges/artboard.d.ts +3 -3
  6. package/dist/bridges/catalog.d.cts +3 -3
  7. package/dist/bridges/catalog.d.ts +3 -3
  8. package/dist/bridges/charts.d.cts +3 -3
  9. package/dist/bridges/charts.d.ts +3 -3
  10. package/dist/bridges/cms.d.cts +3 -3
  11. package/dist/bridges/cms.d.ts +3 -3
  12. package/dist/bridges/code.d.cts +3 -3
  13. package/dist/bridges/code.d.ts +3 -3
  14. package/dist/bridges/doc.d.cts +3 -3
  15. package/dist/bridges/doc.d.ts +3 -3
  16. package/dist/bridges/features.d.cts +3 -3
  17. package/dist/bridges/features.d.ts +3 -3
  18. package/dist/bridges/files.d.cts +3 -3
  19. package/dist/bridges/files.d.ts +3 -3
  20. package/dist/bridges/flow.d.cts +3 -3
  21. package/dist/bridges/flow.d.ts +3 -3
  22. package/dist/bridges/forms.d.cts +3 -3
  23. package/dist/bridges/forms.d.ts +3 -3
  24. package/dist/bridges/git.d.cts +3 -3
  25. package/dist/bridges/git.d.ts +3 -3
  26. package/dist/bridges/grid.d.cts +3 -3
  27. package/dist/bridges/grid.d.ts +3 -3
  28. package/dist/bridges/map.d.cts +3 -3
  29. package/dist/bridges/map.d.ts +3 -3
  30. package/dist/bridges/navigation.d.cts +127 -0
  31. package/dist/bridges/navigation.d.ts +127 -0
  32. package/dist/bridges/passkeys.d.cts +4 -4
  33. package/dist/bridges/passkeys.d.ts +4 -4
  34. package/dist/bridges/scene.d.cts +3 -3
  35. package/dist/bridges/scene.d.ts +3 -3
  36. package/dist/bridges/screens.d.cts +3 -3
  37. package/dist/bridges/screens.d.ts +3 -3
  38. package/dist/bridges/sheets.d.cts +3 -3
  39. package/dist/bridges/sheets.d.ts +3 -3
  40. package/dist/bridges/slides.d.cts +3 -3
  41. package/dist/bridges/slides.d.ts +3 -3
  42. package/dist/bridges/terminal.d.cts +3 -3
  43. package/dist/bridges/terminal.d.ts +3 -3
  44. package/dist/bridges/tui.d.cts +2 -2
  45. package/dist/bridges/tui.d.ts +2 -2
  46. package/dist/bridges/whiteboard.d.cts +3 -3
  47. package/dist/bridges/whiteboard.d.ts +3 -3
  48. package/dist/bridges-navigation.cjs +391 -0
  49. package/dist/bridges-navigation.cjs.map +1 -0
  50. package/dist/bridges-navigation.js +7 -0
  51. package/dist/bridges-navigation.js.map +1 -0
  52. package/dist/bridges-passkeys.cjs.map +1 -1
  53. package/dist/bridges-passkeys.js +1 -1
  54. package/dist/{chunk-PWYEW6NL.js → chunk-G6CRHFWU.js} +2 -2
  55. package/dist/{chunk-PWYEW6NL.js.map → chunk-G6CRHFWU.js.map} +1 -1
  56. package/dist/chunk-JGJHPH65.js +271 -0
  57. package/dist/chunk-JGJHPH65.js.map +1 -0
  58. package/dist/dom-navigation/index.d.cts +164 -0
  59. package/dist/dom-navigation/index.d.ts +164 -0
  60. package/dist/dom-navigation/script.d.cts +3 -0
  61. package/dist/dom-navigation/script.d.ts +3 -0
  62. package/dist/dom-navigation-script.cjs +11 -0
  63. package/dist/dom-navigation-script.cjs.map +1 -0
  64. package/dist/dom-navigation-script.js +9 -0
  65. package/dist/dom-navigation-script.js.map +1 -0
  66. package/dist/dom-navigation.cjs +387 -0
  67. package/dist/dom-navigation.cjs.map +1 -0
  68. package/dist/dom-navigation.js +370 -0
  69. package/dist/dom-navigation.js.map +1 -0
  70. package/dist/index.cjs +31 -31
  71. package/dist/index.cjs.map +1 -1
  72. package/dist/index.d.cts +10 -125
  73. package/dist/index.d.ts +10 -125
  74. package/dist/index.js +12 -275
  75. package/dist/index.js.map +1 -1
  76. package/dist/mcp/index.d.cts +5 -5
  77. package/dist/mcp/index.d.ts +5 -5
  78. package/dist/mcp/stdio.d.cts +3 -3
  79. package/dist/mcp/stdio.d.ts +3 -3
  80. package/dist/presence/index.d.cts +1 -1
  81. package/dist/presence/index.d.ts +1 -1
  82. package/dist/{server-BIcA3ZtK.d.cts → server-1y0n61R5.d.cts} +2 -2
  83. package/dist/{server-DnUyeavY.d.ts → server-vq6qVl3T.d.ts} +2 -2
  84. package/dist/sharing/index.d.cts +3 -3
  85. package/dist/sharing/index.d.ts +3 -3
  86. package/dist/sheets-adapter.d.cts +3 -3
  87. package/dist/sheets-adapter.d.ts +3 -3
  88. package/dist/{tool-host-LVBgCN5m.d.cts → tool-host-D67N2a2h.d.cts} +1 -1
  89. package/dist/{tool-host-Wo0pkY83.d.ts → tool-host-LYfdPE8u.d.ts} +1 -1
  90. package/dist/{types-EcElKOlk.d.cts → types-DP5yQZQU.d.cts} +1 -1
  91. package/dist/{types-BxNRKSVd.d.ts → types-VX_9je7w.d.ts} +1 -1
  92. package/dist/{types-C2DtnHIn.d.cts → types-gzIpsUDE.d.cts} +1 -1
  93. package/dist/{types-C2DtnHIn.d.ts → types-gzIpsUDE.d.ts} +1 -1
  94. package/dist/undo/index.d.cts +2 -2
  95. package/dist/undo/index.d.ts +2 -2
  96. package/package.json +35 -3
package/dist/index.d.cts CHANGED
@@ -1,13 +1,13 @@
1
- import { M as MicroMcpServer } from './server-BIcA3ZtK.cjs';
2
- export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-BIcA3ZtK.cjs';
3
- import { T as ToolHost } from './tool-host-LVBgCN5m.cjs';
4
- export { a as ToolRegistry } from './tool-host-LVBgCN5m.cjs';
1
+ import { M as MicroMcpServer } from './server-1y0n61R5.cjs';
2
+ export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-1y0n61R5.cjs';
3
+ import { T as ToolHost } from './tool-host-D67N2a2h.cjs';
4
+ export { a as ToolRegistry } from './tool-host-D67N2a2h.cjs';
5
5
  export { InProcessTransport, RelayChannel, RelayTransport, attachInProcess, attachRelay } from './mcp/index.cjs';
6
- export { C as CallToolResult, d as ContentBlock, I as InitializeResult, J as JsonObject, a as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, c as ServerCapabilities, S as ServerInfo, h as ToolCallContext, T as ToolDefinition, b as ToolHandler } from './types-C2DtnHIn.cjs';
6
+ export { C as CallToolResult, d as ContentBlock, I as InitializeResult, J as JsonObject, c as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, b as ServerCapabilities, S as ServerInfo, h as ToolCallContext, T as ToolDefinition, a as ToolHandler } from './types-gzIpsUDE.cjs';
7
7
  export { HumanPlusDisposition, HumanPlusEvent, HumanPlusEventPage, HumanPlusEventQuery, HumanPlusEventStore, MemoryHumanPlusEventStore, NewHumanPlusEvent } from './human-plus/index.cjs';
8
8
  export { TuiBridgeOptions, TuiSurfaceRegistryLike, registerTuiBridge } from './bridges/tui.cjs';
9
- import { B as Bridge } from './types-EcElKOlk.cjs';
10
- export { a as BridgeFactory } from './types-EcElKOlk.cjs';
9
+ import { B as Bridge } from './types-DP5yQZQU.cjs';
10
+ export { a as BridgeFactory } from './types-DP5yQZQU.cjs';
11
11
  import { FormFieldDescriptor } from './bridges/forms.cjs';
12
12
  export { FormBridgeAdapter, FormBridgeOptions, registerFormBridge } from './bridges/forms.cjs';
13
13
  export { SheetsBridgeAdapter, SheetsBridgeOptions, registerSheetsBridge } from './bridges/sheets.cjs';
@@ -22,6 +22,8 @@ export { MapBridgeAdapter, MapBridgeOptions, registerMapBridge } from './bridges
22
22
  export { GitBridgeAdapter, GitBridgeOptions, GitProposal, registerGitBridge } from './bridges/git.cjs';
23
23
  export { FilesBridgeAdapter, FilesBridgeOptions, registerFilesBridge } from './bridges/files.cjs';
24
24
  export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalRef, TerminalShell, registerTerminalBridge } from './bridges/terminal.cjs';
25
+ import { NavigationBridgeAdapter } from './bridges/navigation.cjs';
26
+ export { NavigationBridgeOptions, NavigationConfirmRequest, PageAction, PageSnapshot, registerNavigationBridge } from './bridges/navigation.cjs';
25
27
  export { CatalogBridgeAdapter, CatalogBridgeOptions, CatalogCheckoutArgs, CatalogPrice, CatalogProduct, registerCatalogBridge } from './bridges/catalog.cjs';
26
28
  export { FeatureDefinition, FeatureGrant, FeaturesBridgeAdapter, FeaturesBridgeOptions, registerFeaturesBridge } from './bridges/features.cjs';
27
29
  export { PASSKEY_BRIDGE_TOOLS, PasskeyBridgeAdapter, PasskeyBridgeOptions, PasskeyProposal, PasskeySummaryLike, PasskeySupport, PasskeySurfaceState, registerPasskeyBridge } from './bridges/passkeys.cjs';
@@ -45,123 +47,6 @@ export { D as DEFAULT_MCPB_ENTRY_POINT, b as MCPB_MANIFEST_VERSION, c as MCPB_MI
45
47
  import '@particle-academy/fancy-sheets';
46
48
  import '@particle-academy/fancy-slides';
47
49
 
48
- /**
49
- * One interactive element the agent can act on, addressed by a STABLE handle
50
- * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
51
- * scraping. The host builds these in `describe()` (data-co-handle → name/id →
52
- * ARIA role + accessible name).
53
- */
54
- type PageAction = {
55
- /** Stable, opaque handle the agent passes back to act on this element. */
56
- handle: string;
57
- /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
58
- role: string;
59
- /** Accessible name / label. */
60
- label: string;
61
- /** Current value for inputs (omitted/masked for sensitive fields). */
62
- value?: unknown;
63
- /** True when activating this is destructive / submits (agent should stage). */
64
- destructive?: boolean;
65
- };
66
- /** The page as the agent sees it: where it is + what it can do. */
67
- type PageSnapshot = {
68
- url: string;
69
- title: string;
70
- actions: PageAction[];
71
- /** Monotonic host revision. Human input advances it and invalidates stale agent intent. */
72
- revision?: number;
73
- };
74
- /** A write the host may want the human to confirm (trust-but-verify). */
75
- type NavigationConfirmRequest = {
76
- action: "submit" | "click";
77
- handle: string;
78
- label: string;
79
- };
80
- /**
81
- * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
82
- * a DOM walker (see resources/js/agent/CoBrowseProvider.tsx). Every method
83
- * works on stable handles, never raw selectors.
84
- */
85
- type NavigationBridgeAdapter = {
86
- /** Optional fancy-screens screen id for presence targeting. */
87
- screenId?: string;
88
- /** Current location. */
89
- getLocation: () => {
90
- url: string;
91
- title: string;
92
- };
93
- /** Current human-control revision. Omit to disable stale-intent protection. */
94
- getRevision?: () => number;
95
- /** Snapshot of the page's actionable elements (stable handles + labels). */
96
- describe: () => PageSnapshot;
97
- /** Visible text / heading outline for grounding (optional). */
98
- read?: () => string;
99
- /** Navigate to a URL (host wires to router.visit). */
100
- visit: (url: string) => void | Promise<void>;
101
- back?: () => void | Promise<void>;
102
- forward?: () => void | Promise<void>;
103
- /** Scroll to coords or to a handle's element. */
104
- scrollTo: (opts: {
105
- x?: number;
106
- y?: number;
107
- handle?: string;
108
- }) => void;
109
- scrollBy: (dy: number) => void;
110
- /** Set a field's value by handle (host dispatches input/change for React). */
111
- setField: (handle: string, value: unknown) => {
112
- ok: boolean;
113
- error?: string;
114
- };
115
- /** Activate an element by handle. */
116
- click: (handle: string) => {
117
- ok: boolean;
118
- error?: string;
119
- };
120
- /** Submit a form by handle. */
121
- submit: (handle: string) => Promise<{
122
- ok: boolean;
123
- error?: string;
124
- }> | {
125
- ok: boolean;
126
- error?: string;
127
- };
128
- /**
129
- * Viewport rect of a handle's element, for agent-presence rendering (cursor +
130
- * highlight). Returned in tool `meta.rect` so `<CoBrowseCursorLayer>` can show
131
- * the agent acting on the page. Optional — omit and there's just no cursor.
132
- */
133
- rectFor?: (handle: string) => {
134
- x: number;
135
- y: number;
136
- width: number;
137
- height: number;
138
- } | null;
139
- /**
140
- * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
141
- * destructive `page_click` route through this; the host shows a prompt and
142
- * resolves true (proceed) / false (declined).
143
- */
144
- confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
145
- };
146
- type NavigationBridgeOptions = {
147
- adapter: NavigationBridgeAdapter;
148
- /** Identity tagged into activity events (so the human sees who's driving). */
149
- agent?: {
150
- id: string;
151
- name?: string;
152
- color?: string;
153
- };
154
- /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
155
- pendingMode?: boolean;
156
- };
157
- /**
158
- * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
159
- * navigate, scroll, and (with staged confirm) fill + click any page, addressed
160
- * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
161
- * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
162
- */
163
- declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
164
-
165
50
  /**
166
51
  * Reserved node type for a literal string child. Must match fancy-screens'
167
52
  * `TEXT_NODE_TYPE`; duplicated rather than imported to keep this bridge free of
@@ -676,4 +561,4 @@ type SimulateUsersButtonProps = {
676
561
  */
677
562
  declare function SimulateUsersButton({ endpoint, count, label, csrfToken, onTriggered, onError, className, style, }: SimulateUsersButtonProps): react.JSX.Element;
678
563
 
679
- export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, type BridgeContribution, BridgeContributions, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };
564
+ export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, type BridgeContribution, BridgeContributions, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, NavigationBridgeAdapter, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerScreenDocBridge, useCoBrowseSession };
package/dist/index.d.ts CHANGED
@@ -1,13 +1,13 @@
1
- import { M as MicroMcpServer } from './server-DnUyeavY.js';
2
- export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-DnUyeavY.js';
3
- import { T as ToolHost } from './tool-host-Wo0pkY83.js';
4
- export { a as ToolRegistry } from './tool-host-Wo0pkY83.js';
1
+ import { M as MicroMcpServer } from './server-vq6qVl3T.js';
2
+ export { a as McpServerOptions, T as Transport, e as errorResult, r as rpcError, t as textResult } from './server-vq6qVl3T.js';
3
+ import { T as ToolHost } from './tool-host-LYfdPE8u.js';
4
+ export { a as ToolRegistry } from './tool-host-LYfdPE8u.js';
5
5
  export { InProcessTransport, RelayChannel, RelayTransport, attachInProcess, attachRelay } from './mcp/index.js';
6
- export { C as CallToolResult, d as ContentBlock, I as InitializeResult, J as JsonObject, a as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, c as ServerCapabilities, S as ServerInfo, h as ToolCallContext, T as ToolDefinition, b as ToolHandler } from './types-C2DtnHIn.js';
6
+ export { C as CallToolResult, d as ContentBlock, I as InitializeResult, J as JsonObject, c as JsonRpcMessage, e as JsonRpcNotification, f as JsonRpcRequest, g as JsonValue, M as MCP_PROTOCOL_VERSION, b as ServerCapabilities, S as ServerInfo, h as ToolCallContext, T as ToolDefinition, a as ToolHandler } from './types-gzIpsUDE.js';
7
7
  export { HumanPlusDisposition, HumanPlusEvent, HumanPlusEventPage, HumanPlusEventQuery, HumanPlusEventStore, MemoryHumanPlusEventStore, NewHumanPlusEvent } from './human-plus/index.js';
8
8
  export { TuiBridgeOptions, TuiSurfaceRegistryLike, registerTuiBridge } from './bridges/tui.js';
9
- import { B as Bridge } from './types-BxNRKSVd.js';
10
- export { a as BridgeFactory } from './types-BxNRKSVd.js';
9
+ import { B as Bridge } from './types-VX_9je7w.js';
10
+ export { a as BridgeFactory } from './types-VX_9je7w.js';
11
11
  import { FormFieldDescriptor } from './bridges/forms.js';
12
12
  export { FormBridgeAdapter, FormBridgeOptions, registerFormBridge } from './bridges/forms.js';
13
13
  export { SheetsBridgeAdapter, SheetsBridgeOptions, registerSheetsBridge } from './bridges/sheets.js';
@@ -22,6 +22,8 @@ export { MapBridgeAdapter, MapBridgeOptions, registerMapBridge } from './bridges
22
22
  export { GitBridgeAdapter, GitBridgeOptions, GitProposal, registerGitBridge } from './bridges/git.js';
23
23
  export { FilesBridgeAdapter, FilesBridgeOptions, registerFilesBridge } from './bridges/files.js';
24
24
  export { TerminalBridge, TerminalBridgeAdapter, TerminalBridgeOptions, TerminalRef, TerminalShell, registerTerminalBridge } from './bridges/terminal.js';
25
+ import { NavigationBridgeAdapter } from './bridges/navigation.js';
26
+ export { NavigationBridgeOptions, NavigationConfirmRequest, PageAction, PageSnapshot, registerNavigationBridge } from './bridges/navigation.js';
25
27
  export { CatalogBridgeAdapter, CatalogBridgeOptions, CatalogCheckoutArgs, CatalogPrice, CatalogProduct, registerCatalogBridge } from './bridges/catalog.js';
26
28
  export { FeatureDefinition, FeatureGrant, FeaturesBridgeAdapter, FeaturesBridgeOptions, registerFeaturesBridge } from './bridges/features.js';
27
29
  export { PASSKEY_BRIDGE_TOOLS, PasskeyBridgeAdapter, PasskeyBridgeOptions, PasskeyProposal, PasskeySummaryLike, PasskeySupport, PasskeySurfaceState, registerPasskeyBridge } from './bridges/passkeys.js';
@@ -45,123 +47,6 @@ export { D as DEFAULT_MCPB_ENTRY_POINT, b as MCPB_MANIFEST_VERSION, c as MCPB_MI
45
47
  import '@particle-academy/fancy-sheets';
46
48
  import '@particle-academy/fancy-slides';
47
49
 
48
- /**
49
- * One interactive element the agent can act on, addressed by a STABLE handle
50
- * (not a CSS selector) so the agent drives the page the Human+ way — never DOM
51
- * scraping. The host builds these in `describe()` (data-co-handle → name/id →
52
- * ARIA role + accessible name).
53
- */
54
- type PageAction = {
55
- /** Stable, opaque handle the agent passes back to act on this element. */
56
- handle: string;
57
- /** ARIA-ish role: "link" | "button" | "textbox" | "checkbox" | "select" | … */
58
- role: string;
59
- /** Accessible name / label. */
60
- label: string;
61
- /** Current value for inputs (omitted/masked for sensitive fields). */
62
- value?: unknown;
63
- /** True when activating this is destructive / submits (agent should stage). */
64
- destructive?: boolean;
65
- };
66
- /** The page as the agent sees it: where it is + what it can do. */
67
- type PageSnapshot = {
68
- url: string;
69
- title: string;
70
- actions: PageAction[];
71
- /** Monotonic host revision. Human input advances it and invalidates stale agent intent. */
72
- revision?: number;
73
- };
74
- /** A write the host may want the human to confirm (trust-but-verify). */
75
- type NavigationConfirmRequest = {
76
- action: "submit" | "click";
77
- handle: string;
78
- label: string;
79
- };
80
- /**
81
- * Host-provided adapter. In the sandbox this is backed by Inertia's `router` +
82
- * a DOM walker (see resources/js/agent/CoBrowseProvider.tsx). Every method
83
- * works on stable handles, never raw selectors.
84
- */
85
- type NavigationBridgeAdapter = {
86
- /** Optional fancy-screens screen id for presence targeting. */
87
- screenId?: string;
88
- /** Current location. */
89
- getLocation: () => {
90
- url: string;
91
- title: string;
92
- };
93
- /** Current human-control revision. Omit to disable stale-intent protection. */
94
- getRevision?: () => number;
95
- /** Snapshot of the page's actionable elements (stable handles + labels). */
96
- describe: () => PageSnapshot;
97
- /** Visible text / heading outline for grounding (optional). */
98
- read?: () => string;
99
- /** Navigate to a URL (host wires to router.visit). */
100
- visit: (url: string) => void | Promise<void>;
101
- back?: () => void | Promise<void>;
102
- forward?: () => void | Promise<void>;
103
- /** Scroll to coords or to a handle's element. */
104
- scrollTo: (opts: {
105
- x?: number;
106
- y?: number;
107
- handle?: string;
108
- }) => void;
109
- scrollBy: (dy: number) => void;
110
- /** Set a field's value by handle (host dispatches input/change for React). */
111
- setField: (handle: string, value: unknown) => {
112
- ok: boolean;
113
- error?: string;
114
- };
115
- /** Activate an element by handle. */
116
- click: (handle: string) => {
117
- ok: boolean;
118
- error?: string;
119
- };
120
- /** Submit a form by handle. */
121
- submit: (handle: string) => Promise<{
122
- ok: boolean;
123
- error?: string;
124
- }> | {
125
- ok: boolean;
126
- error?: string;
127
- };
128
- /**
129
- * Viewport rect of a handle's element, for agent-presence rendering (cursor +
130
- * highlight). Returned in tool `meta.rect` so `<CoBrowseCursorLayer>` can show
131
- * the agent acting on the page. Optional — omit and there's just no cursor.
132
- */
133
- rectFor?: (handle: string) => {
134
- x: number;
135
- y: number;
136
- width: number;
137
- height: number;
138
- } | null;
139
- /**
140
- * Trust-but-verify hook. When `pendingMode` is on, `page_submit` and
141
- * destructive `page_click` route through this; the host shows a prompt and
142
- * resolves true (proceed) / false (declined).
143
- */
144
- confirm?: (req: NavigationConfirmRequest) => Promise<boolean>;
145
- };
146
- type NavigationBridgeOptions = {
147
- adapter: NavigationBridgeAdapter;
148
- /** Identity tagged into activity events (so the human sees who's driving). */
149
- agent?: {
150
- id: string;
151
- name?: string;
152
- color?: string;
153
- };
154
- /** Route submit + destructive clicks through `adapter.confirm`. Default true. */
155
- pendingMode?: boolean;
156
- };
157
- /**
158
- * registerNavigationBridge — site-wide co-browsing. Lets a connected agent
159
- * navigate, scroll, and (with staged confirm) fill + click any page, addressed
160
- * by stable handles. Pairs with `useCoBrowseSession` (server + relay) and
161
- * `<CoBrowsePresence>` (the human's view of the agent). The 12th Fancy bridge.
162
- */
163
- declare function registerNavigationBridge(host: ToolHost, options: NavigationBridgeOptions): Bridge;
164
-
165
50
  /**
166
51
  * Reserved node type for a literal string child. Must match fancy-screens'
167
52
  * `TEXT_NODE_TYPE`; duplicated rather than imported to keep this bridge free of
@@ -676,4 +561,4 @@ type SimulateUsersButtonProps = {
676
561
  */
677
562
  declare function SimulateUsersButton({ endpoint, count, label, csrfToken, onTriggered, onError, className, style, }: SimulateUsersButtonProps): react.JSX.Element;
678
563
 
679
- export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, type BridgeContribution, BridgeContributions, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, type NavigationBridgeAdapter, type NavigationBridgeOptions, type NavigationConfirmRequest, type PageAction, type PageSnapshot, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };
564
+ export { type AgentActivity, AgentActivityHighlight, type AgentActivityHighlightProps, AgentCursor, type AgentCursorProps, AgentPanel, type AgentPanelProps, Bridge, type BridgeContribution, BridgeContributions, BridgedForm, type BridgedFormProps, CoBrowseCursorLayer, type CoBrowseCursorLayerProps, CoBrowsePresence, type CoBrowsePresenceProps, type CoBrowseSession, type CoBrowseUserEvent, DocAdapter, FormFieldDescriptor, MicroMcpServer, NavigationBridgeAdapter, RelayState, SCREEN_TEXT_NODE_TYPE, type ScreenDocBridgeOptions, type ScreenDocNode, type ScreenDocOp, ScreensActivityBridge, type ScreensActivityBridgeProps, SessionDescriptor, ShareControls, type ShareControlsProps, SimulateUsersButton, type SimulateUsersButtonProps, ToolHost, type UseCoBrowseSessionOptions, buildAgentPrompt, registerScreenDocBridge, useCoBrowseSession };
package/dist/index.js CHANGED
@@ -1,20 +1,22 @@
1
+ import { ShareControls, AgentActivityHighlight, AgentCursor } from './chunk-QDC7MXBH.js';
2
+ export { AgentActivityHighlight, AgentCursor, AgentPanel, ShareControls, buildAgentPrompt } from './chunk-QDC7MXBH.js';
3
+ import './chunk-IJ6JX5VC.js';
4
+ import { createSessionDescriptor, attachSseRelay } from './chunk-6TZ5IBRN.js';
5
+ export { SseRelayTransport, attachSseRelay, buildShareConfig, buildShareUrl, createSessionDescriptor, describeSession, readSessionFromUrl } from './chunk-6TZ5IBRN.js';
1
6
  export { attachHeuristicsSink, mapActivityToEvent as mapActivityToHeuristicsEvent } from './chunk-7R6RMROL.js';
2
7
  export { useUndoStack } from './chunk-3WVXAB3D.js';
8
+ import { registerNavigationBridge } from './chunk-JGJHPH65.js';
9
+ export { registerNavigationBridge } from './chunk-JGJHPH65.js';
3
10
  export { MemoryHumanPlusEventStore } from './chunk-PMI4C5S4.js';
4
11
  export { useSheetsActivityHighlights, useSheetsAdapter } from './chunk-KHKSQEMC.js';
5
12
  import { ConnectorButtons } from './chunk-5HNTNIWY.js';
6
13
  export { CLAUDE_CONNECTORS_URL, CONNECTOR_GLYPHS, CONNECTOR_TARGETS, ClaudeMark, ConnectorButtons, CursorMark, DesktopMark, VscodeMark, WrenchMark, buildCursorDeeplink, buildManualConfig, buildManualConfigSnippet, buildVscodeDeeplink, connectorHref, encodeBase64Json, slugifyServerName } from './chunk-5HNTNIWY.js';
7
14
  export { DEFAULT_MCPB_ENTRY_POINT, MCPB_MANIFEST_VERSION, MCPB_MIN_NODE, buildMcpbManifest, buildMcpbProxyStub } from './chunk-GO2Y6H6U.js';
8
- import { ShareControls, AgentActivityHighlight, AgentCursor } from './chunk-QDC7MXBH.js';
9
- export { AgentActivityHighlight, AgentCursor, AgentPanel, ShareControls, buildAgentPrompt } from './chunk-QDC7MXBH.js';
10
- import './chunk-IJ6JX5VC.js';
11
- import { createSessionDescriptor, attachSseRelay } from './chunk-6TZ5IBRN.js';
12
- export { SseRelayTransport, attachSseRelay, buildShareConfig, buildShareUrl, createSessionDescriptor, describeSession, readSessionFromUrl } from './chunk-6TZ5IBRN.js';
13
15
  export { registerFilesBridge } from './chunk-Z5NL5D4J.js';
14
16
  export { registerTerminalBridge } from './chunk-5ZWNCHZS.js';
15
17
  export { registerCatalogBridge } from './chunk-CS3CHGYC.js';
16
18
  export { registerFeaturesBridge } from './chunk-GVTBMJU6.js';
17
- export { PASSKEY_BRIDGE_TOOLS, registerPasskeyBridge } from './chunk-PWYEW6NL.js';
19
+ export { PASSKEY_BRIDGE_TOOLS, registerPasskeyBridge } from './chunk-G6CRHFWU.js';
18
20
  export { cmsReducer, registerCmsBridge } from './chunk-SWWJUOCY.js';
19
21
  import { registerDocBridge } from './chunk-3HVYUMQF.js';
20
22
  export { registerDocBridge } from './chunk-3HVYUMQF.js';
@@ -35,282 +37,17 @@ export { InProcessTransport, attachInProcess } from './chunk-AFUULW5E.js';
35
37
  import { registerFormBridge } from './chunk-VFWFT3OK.js';
36
38
  export { registerFormBridge } from './chunk-VFWFT3OK.js';
37
39
  export { registerSheetsBridge } from './chunk-VOCUGTZB.js';
38
- import { ensureUndoToolsRegistered, pushUndoEntry } from './chunk-R4XXOGQH.js';
39
40
  export { clearStack as clearUndoStack, ensureUndoToolsRegistered, pushUndoEntry, readHistory as readUndoHistory, redoOne, registerUndoTools, resetAllUndoStacks, undoOne } from './chunk-R4XXOGQH.js';
40
- import { wrapToolWithActivity } from './chunk-2VENWGLZ.js';
41
41
  export { wrapToolWithActivity } from './chunk-2VENWGLZ.js';
42
42
  import { emitActivity, onActivity } from './chunk-C3TYI5TJ.js';
43
43
  export { emitActivity, onActivity, readActivityHistory, resetActivityRegistry } from './chunk-C3TYI5TJ.js';
44
- import { textResult, MicroMcpServer, errorResult } from './chunk-CZV3WUW5.js';
44
+ import { textResult, MicroMcpServer } from './chunk-CZV3WUW5.js';
45
45
  export { MCP_PROTOCOL_VERSION, MicroMcpServer, ToolRegistry, errorResult, rpcError, textResult } from './chunk-CZV3WUW5.js';
46
46
  import { childrenOf, appendOrder } from '@particle-academy/fancy-doc-commons';
47
47
  import { useRef, useState, useEffect, useCallback, useMemo } from 'react';
48
48
  import { jsx, jsxs } from 'react/jsx-runtime';
49
49
  import { createPortal } from 'react-dom';
50
50
 
51
- // src/bridges/navigation.ts
52
- var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
53
- function registerNavigationBridge(host, options) {
54
- const { adapter } = options;
55
- const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
56
- const pendingMode = options.pendingMode ?? true;
57
- const disposers = [];
58
- let groundedRevision = null;
59
- const staleIntent = () => {
60
- const current = adapter.getRevision?.();
61
- if (current === void 0) return null;
62
- if (groundedRevision === null || groundedRevision !== current) {
63
- return errorResult(
64
- `Human took control at page revision ${current}. This agent action was cancelled; call page_describe before acting again.`
65
- );
66
- }
67
- return null;
68
- };
69
- ensureUndoToolsRegistered(host, { defaultAgentId: agent.id });
70
- const target = (label, elementId) => ({
71
- kind: "navigation",
72
- screenId: adapter.screenId,
73
- elementId,
74
- label
75
- });
76
- const reg = (name, description, properties, required, handler, activity) => {
77
- const wrapped = async (args) => {
78
- try {
79
- return await handler(args);
80
- } catch (e) {
81
- return errorResult(e instanceof Error ? e.message : String(e));
82
- }
83
- };
84
- const final = activity ? wrapToolWithActivity(wrapped, {
85
- toolName: name,
86
- agent: { id: agent.id, name: agent.name, color: agent.color },
87
- kind: "navigation",
88
- screenId: adapter.screenId,
89
- resolveTarget: ({ args }) => activity(args)
90
- }) : wrapped;
91
- disposers.push(
92
- host.registerTool(
93
- {
94
- name,
95
- description,
96
- inputSchema: { type: "object", properties, required, additionalProperties: false }
97
- },
98
- final
99
- )
100
- );
101
- };
102
- reg(
103
- "page_describe",
104
- "Describe the current page: its URL, title, and the interactive elements you can act on (each with a stable `handle`, role, and label). Call this first, and again after navigating.",
105
- {},
106
- [],
107
- () => {
108
- const snap = adapter.describe();
109
- const revision = adapter.getRevision?.();
110
- if (revision !== void 0) {
111
- snap.revision = revision;
112
- groundedRevision = revision;
113
- }
114
- const text = [
115
- `URL: ${snap.url}`,
116
- `Title: ${snap.title}`,
117
- "",
118
- ...snap.actions.map((a) => `[${a.handle}] ${a.role}: ${a.label}${a.destructive ? " (destructive)" : ""}`)
119
- ].join("\n");
120
- return textResult(text, snap);
121
- },
122
- () => target("Inspect page")
123
- );
124
- reg(
125
- "page_read",
126
- "Read the page's visible text / heading outline for grounding.",
127
- {},
128
- [],
129
- () => textResult(adapter.read ? adapter.read() : "(host did not provide page text)"),
130
- () => target("Read page")
131
- );
132
- reg(
133
- "page_focus",
134
- "Move the agent's visible focus to an interactive element by stable handle without activating it.",
135
- { handle: { type: "string" } },
136
- ["handle"],
137
- (args) => {
138
- const stale = staleIntent();
139
- if (stale) return stale;
140
- const handle = String(args.handle ?? "");
141
- const action = adapter.describe().actions.find((candidate) => candidate.handle === handle);
142
- if (!action) return errorResult(`No element for handle "${handle}"`);
143
- return textResult(`Focused ${handle}`, {
144
- handle,
145
- rect: adapter.rectFor?.(handle) ?? void 0
146
- });
147
- },
148
- (args) => target(`Focus ${String(args.handle ?? "")}`, String(args.handle ?? ""))
149
- );
150
- reg(
151
- "nav_visit",
152
- "Navigate to a URL (same-site path or absolute). The human watches the page change.",
153
- { url: { type: "string", description: "Path like /packages or an absolute URL." } },
154
- ["url"],
155
- async (args) => {
156
- const stale = staleIntent();
157
- if (stale) return stale;
158
- const url = String(args.url ?? "");
159
- if (!url) return errorResult("url is required");
160
- const scheme = /^([a-zA-Z][a-zA-Z0-9+.-]*):/.exec(url)?.[1]?.toLowerCase();
161
- if (scheme && scheme !== "http" && scheme !== "https") {
162
- return errorResult(
163
- `Refusing to navigate to a '${scheme}:' URL. Only http(s) URLs or same-site paths are allowed.`
164
- );
165
- }
166
- const from = adapter.getLocation().url;
167
- await adapter.visit(url);
168
- pushUndoEntry(agent.id, {
169
- timestamp: Date.now(),
170
- bridgeId: "navigation",
171
- action: "nav_visit",
172
- label: `Navigate to ${url}`,
173
- undo: () => {
174
- adapter.visit(from);
175
- },
176
- redo: () => {
177
- adapter.visit(url);
178
- }
179
- });
180
- return textResult(`Navigated to ${url}`, { url });
181
- },
182
- (args) => target(`Navigate \u2192 ${String(args.url ?? "")}`)
183
- );
184
- reg(
185
- "nav_back",
186
- "Go back to the previous page.",
187
- {},
188
- [],
189
- async () => {
190
- const stale = staleIntent();
191
- if (stale) return stale;
192
- if (!adapter.back) return errorResult("Host did not provide back navigation.");
193
- await adapter.back();
194
- return textResult("Went back");
195
- },
196
- () => target("Back")
197
- );
198
- reg(
199
- "nav_forward",
200
- "Go forward to the next page.",
201
- {},
202
- [],
203
- async () => {
204
- const stale = staleIntent();
205
- if (stale) return stale;
206
- if (!adapter.forward) return errorResult("Host did not provide forward navigation.");
207
- await adapter.forward();
208
- return textResult("Went forward");
209
- },
210
- () => target("Forward")
211
- );
212
- reg(
213
- "nav_scroll_to",
214
- "Scroll the page to absolute coordinates, or to a specific element by its handle.",
215
- {
216
- handle: { type: "string", description: "Scroll this element into view." },
217
- x: { type: "number" },
218
- y: { type: "number" }
219
- },
220
- [],
221
- (args) => {
222
- const stale = staleIntent();
223
- if (stale) return stale;
224
- const handle = typeof args.handle === "string" ? args.handle : void 0;
225
- adapter.scrollTo({
226
- handle,
227
- x: typeof args.x === "number" ? args.x : void 0,
228
- y: typeof args.y === "number" ? args.y : void 0
229
- });
230
- return textResult("Scrolled", handle ? { handle, rect: adapter.rectFor?.(handle) ?? void 0 } : void 0);
231
- },
232
- () => target("Scroll")
233
- );
234
- reg(
235
- "nav_scroll_by",
236
- "Scroll the page by a vertical delta in pixels (negative scrolls up).",
237
- { dy: { type: "number" } },
238
- ["dy"],
239
- (args) => {
240
- const stale = staleIntent();
241
- if (stale) return stale;
242
- adapter.scrollBy(Number(args.dy ?? 0));
243
- return textResult(`Scrolled by ${Number(args.dy ?? 0)}px`);
244
- },
245
- () => target("Scroll")
246
- );
247
- reg(
248
- "page_set_field",
249
- "Set a form field's value by handle. The host updates the controlled input and the human sees it change.",
250
- {
251
- handle: { type: "string" },
252
- value: { description: "Value to set; type matches the field." }
253
- },
254
- ["handle", "value"],
255
- (args) => {
256
- const stale = staleIntent();
257
- if (stale) return stale;
258
- const handle = String(args.handle ?? "");
259
- const res = adapter.setField(handle, args.value);
260
- if (!res.ok) return errorResult(res.error ?? `Could not set ${handle}`);
261
- return textResult(`${handle} \u2190 ${JSON.stringify(args.value)}`, { handle, value: args.value, rect: adapter.rectFor?.(handle) ?? void 0 });
262
- },
263
- (args) => target(`Set ${String(args.handle ?? "")}`, String(args.handle ?? ""))
264
- );
265
- reg(
266
- "page_click",
267
- "Activate an element by handle (link, button, checkbox\u2026). Destructive elements are staged for the human to confirm.",
268
- { handle: { type: "string" } },
269
- ["handle"],
270
- async (args) => {
271
- const stale = staleIntent();
272
- if (stale) return stale;
273
- const handle = String(args.handle ?? "");
274
- const action = adapter.describe().actions.find((a) => a.handle === handle);
275
- const rect = adapter.rectFor?.(handle) ?? void 0;
276
- if (pendingMode && action?.destructive && adapter.confirm) {
277
- const ok = await adapter.confirm({ action: "click", handle, label: action.label });
278
- if (!ok) return errorResult("Declined by user");
279
- }
280
- const res = adapter.click(handle);
281
- if (!res.ok) return errorResult(res.error ?? `Could not click ${handle}`);
282
- return textResult(`Clicked ${handle}`, { handle, rect });
283
- },
284
- (args) => target(`Click ${String(args.handle ?? "")}`, String(args.handle ?? ""))
285
- );
286
- reg(
287
- "page_submit",
288
- "Submit a form by handle. Always staged for the human to confirm when pendingMode is on.",
289
- { handle: { type: "string" } },
290
- ["handle"],
291
- async (args) => {
292
- const stale = staleIntent();
293
- if (stale) return stale;
294
- const handle = String(args.handle ?? "");
295
- const rect = adapter.rectFor?.(handle) ?? void 0;
296
- if (pendingMode && adapter.confirm) {
297
- const ok = await adapter.confirm({ action: "submit", handle, label: handle });
298
- if (!ok) return errorResult("Declined by user");
299
- }
300
- const res = await adapter.submit(handle);
301
- if (!res.ok) return errorResult(res.error ?? "Submit failed");
302
- return textResult(`Submitted ${handle}`, { handle, rect });
303
- },
304
- (args) => target(`Submit ${String(args.handle ?? "")}`, String(args.handle ?? ""))
305
- );
306
- return {
307
- id: "navigation",
308
- title: "Co-browsing",
309
- dispose: () => {
310
- for (const d of disposers) d();
311
- }
312
- };
313
- }
314
51
  var SCREEN_TEXT_NODE_TYPE = "#text";
315
52
  function registerScreenDocBridge(host, options) {
316
53
  const { adapter } = options;
@@ -447,11 +184,11 @@ var BridgeContributions = class {
447
184
  };
448
185
 
449
186
  // src/sharing/use-co-browse-session.ts
450
- var DEFAULT_AGENT2 = { id: "agent", name: "Agent", color: "#a855f7" };
187
+ var DEFAULT_AGENT = { id: "agent", name: "Agent", color: "#a855f7" };
451
188
  var USER = { id: "human", name: "You" };
452
189
  function useCoBrowseSession(options) {
453
190
  const { adapter, extraBridges } = options;
454
- const agent = { ...DEFAULT_AGENT2, ...options.agent ?? {} };
191
+ const agent = { ...DEFAULT_AGENT, ...options.agent ?? {} };
455
192
  const relayBaseUrl = options.relayBaseUrl ?? "/agent-relay";
456
193
  const serverRef = useRef(null);
457
194
  const contributionsRef = useRef(null);
@@ -856,6 +593,6 @@ function SimulateUsersButton({
856
593
  );
857
594
  }
858
595
 
859
- export { BridgeContributions, BridgedForm, CoBrowseCursorLayer, CoBrowsePresence, SCREEN_TEXT_NODE_TYPE, ScreensActivityBridge, SimulateUsersButton, registerNavigationBridge, registerScreenDocBridge, useCoBrowseSession };
596
+ export { BridgeContributions, BridgedForm, CoBrowseCursorLayer, CoBrowsePresence, SCREEN_TEXT_NODE_TYPE, ScreensActivityBridge, SimulateUsersButton, registerScreenDocBridge, useCoBrowseSession };
860
597
  //# sourceMappingURL=index.js.map
861
598
  //# sourceMappingURL=index.js.map