@botiverse/porthole 0.7.0 → 0.9.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 (166) hide show
  1. package/README.md +9 -2
  2. package/THIRD_PARTY_NOTICES.md +421 -0
  3. package/dist/annotate/types.d.ts +40 -4
  4. package/dist/annotate/types.js +6 -1
  5. package/dist/annotate/validate.d.ts +10 -0
  6. package/dist/annotate/validate.js +24 -1
  7. package/dist/bridge/bounded-text.d.ts +34 -0
  8. package/dist/bridge/bounded-text.js +188 -0
  9. package/dist/bridge/bridge.d.ts +25 -5
  10. package/dist/bridge/bridge.js +311 -73
  11. package/dist/bridge/json-data.d.ts +28 -0
  12. package/dist/bridge/json-data.js +86 -0
  13. package/dist/bridge/navigation.d.ts +5 -0
  14. package/dist/bridge/navigation.js +7 -0
  15. package/dist/bridge/refusal.js +1 -0
  16. package/dist/bridge/types.d.ts +32 -1
  17. package/dist/check/page-source.js +1 -1
  18. package/dist/check/page.js +2 -0
  19. package/dist/compile/compile.d.ts +6 -0
  20. package/dist/compile/compile.js +3 -1
  21. package/dist/compile/policy.d.ts +38 -2
  22. package/dist/compile/policy.js +122 -7
  23. package/dist/config/capabilities.d.ts +23 -4
  24. package/dist/config/capabilities.js +12 -2
  25. package/dist/config/schema.d.ts +11 -0
  26. package/dist/config/validate.d.ts +8 -2
  27. package/dist/config/validate.js +28 -6
  28. package/dist/config/warnings.d.ts +20 -0
  29. package/dist/config/warnings.js +25 -0
  30. package/dist/conformance/behavior.js +46 -1
  31. package/dist/conformance/cookies.d.ts +15 -0
  32. package/dist/conformance/cookies.js +80 -0
  33. package/dist/conformance/harness/page.d.ts +1 -0
  34. package/dist/conformance/harness/page.js +9 -2
  35. package/dist/conformance/harness-source.js +1 -1
  36. package/dist/conformance/host-kit.js +5 -1
  37. package/dist/conformance/index.d.ts +10 -0
  38. package/dist/conformance/limits.js +38 -1
  39. package/dist/conformance/runtime.js +10 -0
  40. package/dist/conformance/served.d.ts +2 -0
  41. package/dist/conformance/served.js +737 -4
  42. package/dist/files/paths.js +4 -0
  43. package/dist/guide/gates.d.ts +7 -1
  44. package/dist/guide/gates.js +12 -0
  45. package/dist/guide/guide.js +2 -2
  46. package/dist/guide/runtime.js +11 -3
  47. package/dist/host/create-host.js +81 -39
  48. package/dist/host/pages-of-set.d.ts +43 -0
  49. package/dist/host/pages-of-set.js +196 -0
  50. package/dist/host/types.d.ts +8 -1
  51. package/dist/index.d.ts +5 -4
  52. package/dist/index.js +3 -2
  53. package/dist/mcp/adapter.js +11 -15
  54. package/dist/node/index.d.ts +36 -4
  55. package/dist/node/index.js +402 -101
  56. package/dist/platform/types.d.ts +9 -0
  57. package/dist/platform/web.js +8 -0
  58. package/dist/presets/presets.d.ts +16 -8
  59. package/dist/presets/presets.js +39 -8
  60. package/dist/protocol/live-data.d.ts +6 -2
  61. package/dist/protocol/live-data.js +20 -1
  62. package/dist/protocol/mcp-apps.d.ts +13 -2
  63. package/dist/protocol/mcp-apps.js +10 -2
  64. package/dist/protocol/message-text.d.ts +8 -0
  65. package/dist/protocol/message-text.js +29 -0
  66. package/dist/protocol/runtime-calls.js +3 -0
  67. package/dist/protocol/shell-adapter.js +16 -22
  68. package/dist/react/context-notice.d.ts +32 -0
  69. package/dist/react/context-notice.js +28 -0
  70. package/dist/react/dialog.js +62 -18
  71. package/dist/react/frame.d.ts +18 -3
  72. package/dist/react/frame.js +79 -2
  73. package/dist/react/index.d.ts +2 -1
  74. package/dist/react/index.js +2 -1
  75. package/dist/runtime/contract.d.ts +9 -1
  76. package/dist/runtime/contract.js +31 -2
  77. package/dist/runtime/db.d.ts +41 -6
  78. package/dist/runtime/db.js +120 -16
  79. package/dist/runtime/declaration.d.ts +15 -1
  80. package/dist/runtime/declaration.js +184 -87
  81. package/dist/runtime/requests.js +27 -11
  82. package/dist/runtime/types.generated.js +1 -1
  83. package/dist/server/files.d.ts +5 -0
  84. package/dist/server/files.js +22 -7
  85. package/dist/server/host.d.ts +18 -1
  86. package/dist/server/host.js +132 -2
  87. package/dist/server/index.d.ts +1 -1
  88. package/dist/server/index.js +1 -1
  89. package/dist/server/peer.d.ts +4 -0
  90. package/dist/server/peer.js +19 -0
  91. package/dist/server/proxy.d.ts +6 -0
  92. package/dist/server/proxy.js +12 -3
  93. package/dist/server/server.js +113 -26
  94. package/dist/server/types.d.ts +6 -3
  95. package/dist/shell/annotate.d.ts +7 -2
  96. package/dist/shell/annotate.js +233 -15
  97. package/dist/shell/document.d.ts +8 -0
  98. package/dist/shell/document.js +3 -0
  99. package/dist/shell/runtime.js +361 -14
  100. package/docs/ADOPTING.md +119 -14
  101. package/docs/ARCHITECTURE.md +15 -4
  102. package/docs/DECISIONS.md +1610 -9
  103. package/docs/DESIGN.md +114 -30
  104. package/docs/THREAT_MODEL.md +652 -0
  105. package/package.json +14 -3
  106. package/src/annotate/types.ts +37 -5
  107. package/src/annotate/validate.ts +30 -1
  108. package/src/bridge/bounded-text.ts +240 -0
  109. package/src/bridge/bridge.ts +373 -84
  110. package/src/bridge/json-data.ts +95 -0
  111. package/src/bridge/navigation.ts +10 -0
  112. package/src/bridge/refusal.ts +1 -0
  113. package/src/bridge/types.ts +30 -1
  114. package/src/check/page.ts +2 -0
  115. package/src/compile/compile.ts +9 -1
  116. package/src/compile/policy.ts +130 -7
  117. package/src/config/capabilities.ts +22 -3
  118. package/src/config/schema.ts +11 -0
  119. package/src/config/validate.ts +43 -5
  120. package/src/config/warnings.ts +42 -0
  121. package/src/conformance/behavior.ts +54 -1
  122. package/src/conformance/cookies.ts +93 -0
  123. package/src/conformance/harness/page.ts +11 -2
  124. package/src/conformance/host-kit.ts +10 -1
  125. package/src/conformance/index.ts +10 -0
  126. package/src/conformance/limits.ts +39 -1
  127. package/src/conformance/runtime.ts +21 -0
  128. package/src/conformance/served.ts +888 -4
  129. package/src/files/paths.ts +4 -0
  130. package/src/guide/gates.ts +13 -1
  131. package/src/guide/guide.ts +3 -3
  132. package/src/guide/runtime.ts +12 -3
  133. package/src/host/create-host.ts +88 -38
  134. package/src/host/pages-of-set.ts +226 -0
  135. package/src/host/types.ts +15 -1
  136. package/src/index.ts +5 -0
  137. package/src/mcp/adapter.ts +16 -20
  138. package/src/node/index.ts +507 -116
  139. package/src/platform/types.ts +6 -0
  140. package/src/platform/web.ts +10 -0
  141. package/src/presets/presets.ts +60 -17
  142. package/src/protocol/live-data.ts +31 -3
  143. package/src/protocol/mcp-apps.ts +11 -2
  144. package/src/protocol/message-text.ts +36 -0
  145. package/src/protocol/runtime-calls.ts +3 -0
  146. package/src/protocol/shell-adapter.ts +27 -23
  147. package/src/react/context-notice.tsx +95 -0
  148. package/src/react/dialog.tsx +77 -17
  149. package/src/react/frame.tsx +107 -2
  150. package/src/react/index.ts +8 -1
  151. package/src/runtime/contract.ts +36 -2
  152. package/src/runtime/db.ts +140 -20
  153. package/src/runtime/declaration.ts +227 -89
  154. package/src/runtime/requests.ts +27 -11
  155. package/src/runtime/types.generated.ts +1 -1
  156. package/src/server/files.ts +29 -11
  157. package/src/server/host.ts +158 -3
  158. package/src/server/index.ts +1 -0
  159. package/src/server/peer.ts +21 -0
  160. package/src/server/proxy.ts +13 -3
  161. package/src/server/server.ts +139 -36
  162. package/src/server/types.ts +6 -3
  163. package/src/shell/annotate.ts +233 -15
  164. package/src/shell/document.ts +8 -0
  165. package/src/shell/runtime.ts +361 -14
  166. package/types/runtime/v1/context.d.ts +13 -2
@@ -1,5 +1,10 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
2
  export declare const withoutSealedAddresses: (text: string) => string;
3
+ /**
4
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
5
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
6
+ */
7
+ export declare const cutText: (text: string, max: number) => string;
3
8
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
4
9
  export declare function addressWithoutQuery(url: string): string;
5
10
  /** What the content's errors say about a navigation the shell cancelled. */
@@ -10,6 +10,13 @@
10
10
  */
11
11
  const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
12
12
  export const withoutSealedAddresses = (text) => text.replace(SEALED, "./");
13
+ /** A sealed address's access, cut off by the end of the text: no longer one `SEALED` matches. */
14
+ const UNFINISHED = /\/__porthole\/f\/[A-Za-z0-9_-]*$/u;
15
+ /**
16
+ * `text`, at most `max` characters (S05, P095): a cut inside a sealed address's access drops what
17
+ * of it is left, so a text cut before it is scrubbed tells no part of one.
18
+ */
19
+ export const cutText = (text, max) => text.length <= max ? text : text.slice(0, max).replace(UNFINISHED, "");
13
20
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
14
21
  export function addressWithoutQuery(url) {
15
22
  // A page's own file (P084), as the shell names it: its path, without query or fragment.
@@ -100,6 +100,7 @@ const CODES = {
100
100
  redirected: "denied",
101
101
  muted: "denied",
102
102
  "no-consent": "not_allowed",
103
+ "no-show": "not_allowed",
103
104
  denied: "denied",
104
105
  "rate-limited": "rate_limited",
105
106
  failed: "failed",
@@ -81,6 +81,13 @@ export type ConfirmRequest = {
81
81
  readonly capability: N;
82
82
  readonly args: CapabilityArgs[N];
83
83
  readonly display: ConfirmDisplay;
84
+ /**
85
+ * A confirmation only (never a consent's request): the runtime methods whose own gates
86
+ * (`CapabilityConfig.methodGates`, the contract's) asked for it, of those the call runs (P094):
87
+ * a db batch's writes' ops that need a yes, so a dialog can lead with them. Absent where only
88
+ * the host function's own gates ask.
89
+ */
90
+ readonly askedBy?: readonly string[];
84
91
  };
85
92
  }[CapabilityName];
86
93
  /**
@@ -96,6 +103,17 @@ export type ConfirmAnswer = boolean | "accepted" | "declined" | "redirected";
96
103
  * its own "yes" button, rather than resolving the promise and letting the effect run after.
97
104
  */
98
105
  export type Proceed = () => void;
106
+ /**
107
+ * Puts a call's whole effect in front of the person, outside every frame (the `show` gate, P100):
108
+ * a `setModelContext` update's text and structured content, which the model reads at its next
109
+ * turns. It asks nothing; the call goes once it returns (or its promise resolves), so it resolves
110
+ * only once this very update is visible: drawn, not queued behind a render (after the review). An
111
+ * update the person never saw, because a later one of the display replaced it first, rejects:
112
+ * the call doesn't go. One that throws or rejects stops the call: nobody saw it. Each update
113
+ * replaces the display's last (MCP Apps: the host sends the model the last one), so a surface
114
+ * shows the latest per display.
115
+ */
116
+ export type Show = (request: ConfirmRequest) => void | Promise<void>;
99
117
  /**
100
118
  * Asks a person. Resolves with their answer. The host's UI, or the React binding's default
101
119
  * dialog; drawn outside the frame, never inside it. `proceed` (optional to use) runs the effect
@@ -120,9 +138,11 @@ export type Refusal =
120
138
  | "muted"
121
139
  /** It is `consent`-gated and there is no `consent` function. */
122
140
  | "no-consent"
141
+ /** It is `show`-gated and there is no `show` function: nobody could see it (P100). */
142
+ | "no-show"
123
143
  /** The host's `consent` said no (for this display's life). */
124
144
  | "denied" | "rate-limited"
125
- /** The host's handler threw or rejected. */
145
+ /** The host's handler threw or rejected (or its `show` did: nobody saw the call, P100). */
126
146
  | "failed"
127
147
  /**
128
148
  * The display's page declared capabilities and not this one (P086): a built-in needs none, any
@@ -158,6 +178,17 @@ export interface CallOptions {
158
178
  readonly subscription?: Pick<SubscriptionContext, "changed" | "signal">;
159
179
  /** `readData`: the host's cache may answer, marked stale (the content subscribes to it). */
160
180
  readonly stale?: boolean;
181
+ /**
182
+ * `readData`: a result the host already gave for this read (a subscription's `changed(result)`,
183
+ * the fresh read after a stale answer), and the URI it was given for. It answers the read after
184
+ * every gate a read has, without the handler or the cache (P094: a kept result is never a way
185
+ * past the read's gates); a `uri` that isn't the read's is refused (`invalid`). Ignored for any
186
+ * capability but `readData`.
187
+ */
188
+ readonly held?: {
189
+ readonly uri: string;
190
+ readonly value: unknown;
191
+ };
161
192
  }
162
193
  /** What adapters call; one per display. */
163
194
  export interface HostFunctionBridge {