@botiverse/porthole 0.15.3 → 0.16.1

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 (118) hide show
  1. package/CHANGELOG.md +70 -0
  2. package/dist/annotate/types.d.ts +15 -1
  3. package/dist/annotate/validate.js +19 -1
  4. package/dist/bridge/bridge.d.ts +1 -8
  5. package/dist/bridge/bridge.js +0 -7
  6. package/dist/bridge/types.d.ts +1 -1
  7. package/dist/check/page-source.js +1 -1
  8. package/dist/check/page.js +1 -1
  9. package/dist/compile/policy.d.ts +0 -7
  10. package/dist/compile/policy.js +1 -10
  11. package/dist/config/capabilities.d.ts +8 -14
  12. package/dist/config/capabilities.js +4 -5
  13. package/dist/config/schema.d.ts +2 -13
  14. package/dist/config/validate.js +0 -24
  15. package/dist/conformance/behavior.js +26 -37
  16. package/dist/conformance/clipboard.js +47 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/displays/displays.js +1 -3
  19. package/dist/guide/limits.js +1 -1
  20. package/dist/guide/runtime.js +1 -1
  21. package/dist/host/create-host.d.ts +1 -1
  22. package/dist/host/create-host.js +8 -52
  23. package/dist/host/door.d.ts +1 -1
  24. package/dist/host/locate.d.ts +1 -1
  25. package/dist/host/locate.js +2 -2
  26. package/dist/host/outcome.d.ts +5 -12
  27. package/dist/host/outcome.js +8 -16
  28. package/dist/host/types.d.ts +6 -22
  29. package/dist/index.d.ts +2 -4
  30. package/dist/index.js +2 -4
  31. package/dist/isolation/served.d.ts +4 -14
  32. package/dist/isolation/served.js +7 -28
  33. package/dist/isolation/types.d.ts +2 -25
  34. package/dist/isolation/types.js +0 -23
  35. package/dist/platform/focus-field.d.ts +11 -0
  36. package/dist/platform/focus-field.js +18 -0
  37. package/dist/platform/types.d.ts +7 -23
  38. package/dist/platform/web.js +8 -106
  39. package/dist/presets/presets.d.ts +0 -2
  40. package/dist/presets/presets.js +0 -1
  41. package/dist/react/frame.d.ts +0 -8
  42. package/dist/react/frame.js +0 -4
  43. package/dist/runtime/contract.d.ts +2 -2
  44. package/dist/runtime/contract.js +2 -2
  45. package/dist/runtime/types.generated.js +6 -6
  46. package/dist/server/files.js +7 -23
  47. package/dist/server/host.d.ts +1 -1
  48. package/dist/server/index.d.ts +1 -1
  49. package/dist/server/index.js +4 -6
  50. package/dist/server/naming.js +1 -1
  51. package/dist/server/server.js +28 -166
  52. package/dist/server/types.d.ts +7 -7
  53. package/dist/shell/annotate.d.ts +3 -0
  54. package/dist/shell/annotate.js +15 -5
  55. package/dist/shell/plan.d.ts +0 -5
  56. package/dist/shell/plan.js +2 -4
  57. package/dist/shell/runtime.js +1 -268
  58. package/docs/ADOPTING.md +398 -1081
  59. package/docs/DECISIONS.md +172 -10
  60. package/docs/DESIGN.md +1114 -1388
  61. package/docs/PRINCIPLES.md +85 -1
  62. package/docs/THREAT_MODEL.md +658 -1127
  63. package/package.json +1 -1
  64. package/src/annotate/types.ts +12 -1
  65. package/src/annotate/validate.ts +23 -1
  66. package/src/bridge/bridge.ts +1 -17
  67. package/src/bridge/types.ts +1 -1
  68. package/src/check/page.ts +1 -1
  69. package/src/compile/policy.ts +1 -11
  70. package/src/config/capabilities.ts +8 -14
  71. package/src/config/schema.ts +2 -13
  72. package/src/config/validate.ts +0 -28
  73. package/src/conformance/behavior.ts +50 -52
  74. package/src/conformance/clipboard.ts +56 -1
  75. package/src/displays/displays.ts +1 -3
  76. package/src/guide/limits.ts +1 -1
  77. package/src/guide/runtime.ts +1 -1
  78. package/src/host/create-host.ts +8 -53
  79. package/src/host/door.ts +1 -1
  80. package/src/host/locate.ts +2 -2
  81. package/src/host/outcome.ts +8 -21
  82. package/src/host/types.ts +6 -20
  83. package/src/index.ts +2 -4
  84. package/src/isolation/served.ts +6 -34
  85. package/src/isolation/types.ts +2 -31
  86. package/src/platform/focus-field.ts +18 -0
  87. package/src/platform/types.ts +7 -22
  88. package/src/platform/web.ts +8 -129
  89. package/src/presets/presets.ts +0 -3
  90. package/src/react/frame.tsx +0 -10
  91. package/src/runtime/contract.ts +4 -4
  92. package/src/runtime/types.generated.ts +6 -6
  93. package/src/server/files.ts +4 -19
  94. package/src/server/host.ts +1 -1
  95. package/src/server/index.ts +4 -16
  96. package/src/server/naming.ts +1 -1
  97. package/src/server/server.ts +29 -189
  98. package/src/server/types.ts +7 -7
  99. package/src/shell/annotate.ts +15 -5
  100. package/src/shell/plan.ts +2 -9
  101. package/src/shell/runtime.ts +1 -268
  102. package/types/runtime/v1/artifact.d.ts +2 -3
  103. package/types/runtime/v1/assets.d.ts +1 -1
  104. package/types/runtime/v1/chat.d.ts +2 -2
  105. package/types/runtime/v1/comments.d.ts +1 -1
  106. package/types/runtime/v1/downloads.d.ts +2 -2
  107. package/types/runtime/v1/links.d.ts +2 -2
  108. package/dist/platform/focus-guard.d.ts +0 -288
  109. package/dist/platform/focus-guard.js +0 -838
  110. package/dist/server/nested.d.ts +0 -66
  111. package/dist/server/nested.js +0 -121
  112. package/dist/shell/frame.d.ts +0 -28
  113. package/dist/shell/frame.js +0 -407
  114. package/docs/ARCHITECTURE.md +0 -359
  115. package/docs/OBJECTIVES.md +0 -116
  116. package/src/platform/focus-guard.ts +0 -1114
  117. package/src/server/nested.ts +0 -157
  118. package/src/shell/frame.ts +0 -444
@@ -1,4 +1,4 @@
1
- # Principles
1
+ # Principles and objectives
2
2
 
3
3
  These are the rules we use to make decisions quickly. When a choice is unclear,
4
4
  pick the option that best satisfies these, write it down in
@@ -153,3 +153,87 @@ same config as the sandbox and the shell.
153
153
  - **Rules out.** Shipping a shell and leaving the manual to each host; a manual
154
154
  that lists variables or limits the shell does not actually enforce; prose
155
155
  guidance that no test checks against real renders.
156
+
157
+ ## Objectives
158
+
159
+ What Porthole is for and how we know it does it. OBJECTIVE n is cited by its number.
160
+
161
+ ### What Porthole is for
162
+
163
+ Any app that wants the "show content made by an agent" ability — like the inline
164
+ visuals and standalone pages in ChatGPT and the Claude app — should be able to
165
+ embed Porthole and get a working, safe display out of the box, plus the manual
166
+ that teaches the agent to write for it.
167
+
168
+ The subject, stated generally, is **HTML drawn by an agent that may optionally
169
+ interact with the agent** — and that interaction is just one host function among
170
+ several. "Out of the box" means: a host picks a preset, passes theme tokens and
171
+ callbacks, and receives a safe display plus a generated agent manual.
172
+
173
+ ### Objectives and success criteria
174
+
175
+ 1. **Show untrusted agent HTML without putting the host at risk.**
176
+ - *Success:* the conformance/leak suite passes on Chromium, WebKit and
177
+ Firefox — every egress and escape probe attempts its channel and observes
178
+ nothing; the content cannot reach the host origin, its storage, its DOM, or
179
+ its credentials.
180
+
181
+ 2. **One config generates the sandbox, the shell, and the manual, in agreement.**
182
+ - *Success:* for every preset, a test derives the CSP, the shell's wired host
183
+ functions, and the generated guide from the same config and asserts they
184
+ match — the guide names only variables the shell injects and only
185
+ capabilities the CSP and bridge allow; changing the config changes all
186
+ three together.
187
+
188
+ 3. **Speak the MCP Apps standard, proven against the reference implementation.**
189
+ - *Success:* the MCP Apps preset renders and interacts with the official
190
+ ext-apps example servers **unmodified** (initialize handshake, tool input
191
+ and result, size and theme changes, open-link and message), driven in the
192
+ leak suite.
193
+
194
+ 4. **Embed with near-zero config across the modes.**
195
+ - *Success:* a host mounts an inline widget, an artifact page, an MCP Apps
196
+ view and a URL frame each in a few lines using only a preset, theme tokens
197
+ and callbacks; the framework-agnostic core and the React binding both do
198
+ this; no host-specific code lives in the core.
199
+
200
+ 5. **Ship the agent manual as a first-class output.**
201
+ - *Success:* each preset produces an agent-facing guide and tool description
202
+ from its config; a real agent that reads the guide produces content that
203
+ renders within the sandbox and reads correctly at the target widths in light
204
+ and dark, checked by rendering the guide's own examples in the leak suite.
205
+
206
+ ### Non-goals
207
+
208
+ - **Host-drawn DSL rendering.** Rendering a JSON/JSX/remote-DOM UI description
209
+ with the host's own native components (A2UI, json-render, remote-dom, JSX
210
+ preview) is a separate concern and a different project. Porthole is the HTML
211
+ sandbox only.
212
+ - **A component vocabulary inside the sandbox.** Content is plain HTML and SVG,
213
+ taught by the generated manual; a consistent look comes from the injected theme
214
+ variables and, at most, plain base CSS for native elements, never from tags and
215
+ props an agent must learn (P015). Nor is Porthole a design-system library.
216
+ - **A new widget-side protocol.** The contract is MCP Apps; we do not define an
217
+ alternative (PRINCIPLE 2).
218
+ - **A shell or egress control for URL mode.** A URL frame is someone else's
219
+ running app: Porthole gives it isolation and access auth, nothing more (P020).
220
+ - **Operating infrastructure.** The serving part (`/server`) is a request handler a
221
+ host mounts in its own backend; Porthole runs no service, domain or certificate
222
+ of its own.
223
+ - **Being an agent framework or an MCP server.** Porthole is host-side rendering
224
+ and isolation. It does not run models, implement an MCP server, or decide
225
+ product policy (PRINCIPLE 8).
226
+
227
+ ### Who the users are
228
+
229
+ - **Host app developers** who want to show agent-made HTML in a chat or canvas UI
230
+ and do not want to build or audit an isolation layer themselves. They are the
231
+ primary users: they embed the library and pick a preset.
232
+ - **Agents (and the people prompting them)** who write the HTML. They are served
233
+ indirectly: the generated manual is written for them, and the sandbox is the
234
+ environment their code runs in.
235
+ - **MCP App authors** who build standard MCP Apps and want them to render in any
236
+ Porthole-based host unmodified.
237
+
238
+ The first adopter is a normal user of the public API, with no privileged path
239
+ (PRINCIPLE 9).