@botiverse/porthole 0.4.0 → 0.5.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 (73) hide show
  1. package/README.md +3 -1
  2. package/dist/bridge/bridge.d.ts +16 -2
  3. package/dist/bridge/bridge.js +65 -12
  4. package/dist/bridge/types.d.ts +44 -6
  5. package/dist/check/lint.js +2 -2
  6. package/dist/check/page-source.js +1 -1
  7. package/dist/check/page.js +5 -0
  8. package/dist/compile/policy.d.ts +5 -0
  9. package/dist/compile/policy.js +18 -1
  10. package/dist/config/capabilities.d.ts +25 -2
  11. package/dist/config/capabilities.js +13 -0
  12. package/dist/config/schema.d.ts +7 -0
  13. package/dist/config/validate.js +14 -3
  14. package/dist/conformance/harness/page.js +1 -0
  15. package/dist/conformance/harness-source.js +1 -1
  16. package/dist/displays/displays.d.ts +1 -1
  17. package/dist/guide/guide.js +48 -8
  18. package/dist/host/create-host.js +5 -1
  19. package/dist/host/types.d.ts +12 -1
  20. package/dist/index.d.ts +4 -3
  21. package/dist/index.js +2 -1
  22. package/dist/libraries/files.generated.d.ts +1 -0
  23. package/dist/libraries/files.generated.js +8 -0
  24. package/dist/libraries/libraries.d.ts +36 -0
  25. package/dist/libraries/libraries.js +40 -0
  26. package/dist/mcp/adapter.js +31 -2
  27. package/dist/presets/presets.d.ts +15 -0
  28. package/dist/presets/presets.js +27 -2
  29. package/dist/protocol/live-data.d.ts +27 -0
  30. package/dist/protocol/live-data.js +98 -0
  31. package/dist/protocol/mcp-apps.d.ts +9 -0
  32. package/dist/protocol/mcp-apps.js +11 -0
  33. package/dist/protocol/shell-adapter.js +35 -2
  34. package/dist/react/dialog.js +2 -0
  35. package/dist/react/frame.d.ts +15 -1
  36. package/dist/react/frame.js +35 -1
  37. package/dist/server/libraries.d.ts +7 -0
  38. package/dist/server/libraries.js +27 -0
  39. package/dist/server/server.js +2 -1
  40. package/dist/shell/annotate.js +4 -1
  41. package/dist/shell/runtime.d.ts +5 -1
  42. package/dist/shell/runtime.js +165 -1
  43. package/docs/ADOPTING.md +57 -1
  44. package/docs/DECISIONS.md +129 -0
  45. package/docs/DESIGN.md +19 -6
  46. package/package.json +3 -1
  47. package/src/bridge/bridge.ts +85 -13
  48. package/src/bridge/types.ts +45 -3
  49. package/src/check/lint.ts +2 -1
  50. package/src/check/page.ts +5 -0
  51. package/src/compile/policy.ts +19 -1
  52. package/src/config/capabilities.ts +21 -0
  53. package/src/config/schema.ts +7 -0
  54. package/src/config/validate.ts +21 -3
  55. package/src/conformance/harness/page.ts +1 -0
  56. package/src/displays/displays.ts +1 -1
  57. package/src/guide/guide.ts +57 -7
  58. package/src/host/create-host.ts +5 -1
  59. package/src/host/types.ts +12 -1
  60. package/src/index.ts +13 -0
  61. package/src/libraries/files.generated.ts +8 -0
  62. package/src/libraries/libraries.ts +64 -0
  63. package/src/mcp/adapter.ts +40 -2
  64. package/src/presets/presets.ts +46 -3
  65. package/src/protocol/live-data.ts +138 -0
  66. package/src/protocol/mcp-apps.ts +12 -0
  67. package/src/protocol/shell-adapter.ts +35 -3
  68. package/src/react/dialog.tsx +2 -0
  69. package/src/react/frame.tsx +54 -0
  70. package/src/server/libraries.ts +28 -0
  71. package/src/server/server.ts +2 -1
  72. package/src/shell/annotate.ts +4 -1
  73. package/src/shell/runtime.ts +165 -1
@@ -340,7 +340,10 @@ export const ANNOTATE_RUNTIME = String.raw`if (declared("annotate")) {
340
340
  // The shell's own layer, over the content: marks, the outline of what would be picked.
341
341
  let layer = null;
342
342
  let shadow = null;
343
- const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.3);box-shadow:inset 0 -2px 0 rgba(202,138,4,.8)}.mark.element{background:rgba(250,204,21,.12);box-shadow:none;outline:2px solid rgba(202,138,4,.85);outline-offset:1px}.mark.active{background:rgba(250,204,21,.5)}.mark.element.active{background:rgba(250,204,21,.22);outline-width:3px}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{background:rgba(250,204,21,.9)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
343
+ // Marks lie over the content's text, so their fill is light (the text under them keeps its
344
+ // contrast, on a light page and a dark one alike) and an underline or outline says where
345
+ // they are; the active one and a flash add a ring around it, not more fill over its words.
346
+ const STYLE = ".mark{position:absolute;border-radius:2px;background:rgba(250,204,21,.18);box-shadow:inset 0 -2px 0 rgba(234,179,8,.95)}.mark.element{background:rgba(250,204,21,.07);box-shadow:none;outline:2px solid rgba(234,179,8,.9);outline-offset:1px}.mark.active{background:rgba(250,204,21,.26);box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 2px rgba(234,179,8,.45)}.mark.element.active{background:rgba(250,204,21,.12);box-shadow:none;outline-width:3px}.mark.flash{animation:flash 1.8s ease-out}@keyframes flash{from{box-shadow:inset 0 -3px 0 rgb(234,179,8),0 0 0 6px rgba(250,204,21,.6)}}.hover{position:absolute;outline:2px solid #2563eb;outline-offset:1px;background:rgba(37,99,235,.12)}.tag{position:absolute;max-width:70vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:12px/18px ui-monospace,SFMono-Regular,Menlo,monospace;padding:0 6px;border-radius:4px;background:#1e293b;color:#fff}";
344
347
  const ensureLayer = () => {
345
348
  if (layer === null) {
346
349
  layer = createElement.call(document, "div");
@@ -16,7 +16,11 @@
16
16
  * shadow DOM through `setHTMLUnsafe`, `parseHTMLUnsafe`, `document.write`);
17
17
  * 5. keeps content off the clipboard: the async Clipboard API refuses, `execCommand` won't copy or
18
18
  * cut, and copy and cut events never reach content, so what a person copies is what they
19
- * selected (P051). Copy buttons go through the host (`copyText`, P052).
19
+ * selected (P051). Copy buttons go through the host (`copyText`, P052);
20
+ * 6. cancels every navigation the frame starts to another document (P079), before it sends a
21
+ * request: a navigation carries data out in its URL, and the embedding page's `frame-src`,
22
+ * the wall for that, must let served frames reach their own content origins. (Opaque frames
23
+ * get no navigate events: there `frame-src` is the wall.)
20
24
  * A whole document (an artifact page, an MCP Apps view) is never written in: it is parsed inert,
21
25
  * imported, and its scripts run in order, as a fragment's are.
22
26
  *
@@ -72,6 +76,35 @@ export const SHELL_RUNTIME = String.raw`(() => {
72
76
  }
73
77
  }
74
78
 
79
+ // No navigation to another document (P079): a frame that navigates itself carries data out in
80
+ // the URL, and the embedding page's frame-src, the other wall, lets served frames reach every
81
+ // content origin. (An opaque frame gets no navigate events, as the spec says for opaque
82
+ // origins, measured: there frame-src is the wall, P033.) The navigate event comes before any request for every
83
+ // navigation this document starts (location, a link, window.open(…, "_self"), a refresh), and
84
+ // cancelling it stops it. Ours is the first listener, and reads the event through the platform's
85
+ // own getters, kept now, so content can neither stop it nor lie to it. Same-document ones (an
86
+ // anchor) go on, and so do reloads: the same address, on the frame's own origin (or none, in a
87
+ // srcdoc frame), which history can change only within that origin. The host's own (a new
88
+ // frame) are none of this document's.
89
+ const navigationApi = window.navigation;
90
+ const getterOf = (proto, name) => {
91
+ const descriptor = proto ? Object.getOwnPropertyDescriptor(proto, name) : undefined;
92
+ return descriptor && typeof descriptor.get === "function" ? descriptor.get : null;
93
+ };
94
+ const navigateProto = typeof NavigateEvent === "function" ? NavigateEvent.prototype : null;
95
+ const destinationOf = getterOf(navigateProto, "destination");
96
+ const navigationTypeOf = getterOf(navigateProto, "navigationType");
97
+ const sameDocumentOf = getterOf(typeof NavigationDestination === "function" ? NavigationDestination.prototype : null, "sameDocument");
98
+ const preventNavigation = Event.prototype.preventDefault;
99
+ const applyOf = Reflect.apply;
100
+ if (navigationApi && typeof navigationApi.addEventListener === "function" && destinationOf !== null && sameDocumentOf !== null && navigationTypeOf !== null) {
101
+ navigationApi.addEventListener("navigate", (event) => {
102
+ if (!applyOf(sameDocumentOf, applyOf(destinationOf, event, []), []) && applyOf(navigationTypeOf, event, []) !== "reload") {
103
+ applyOf(preventNavigation, event, []);
104
+ }
105
+ }, true);
106
+ }
107
+
75
108
  // No nested frames (each would be a fresh realm with WebRTC intact), no resource hints and no
76
109
  // refreshes (they reach the network outside the CSP's fetch directives). Removed as they are
77
110
  // added: a mutation observer's microtask runs before a child frame's document loads.
@@ -710,6 +743,132 @@ export const SHELL_RUNTIME = String.raw`(() => {
710
743
  });
711
744
  }
712
745
 
746
+ // Data (P079): readData reads a resource the host names, subscribeData follows one, through
747
+ // MCP's resources/* requests, which the host gates (the viewer's consent, a rate). A value is the
748
+ // first content's: JSON parsed when it says it is JSON, else its text.
749
+ let resourceUpdated = (_uri) => {};
750
+ const valueOf = (result) => {
751
+ const first = result && Array.isArray(result.contents) ? result.contents[0] : undefined;
752
+ if (first === null || typeof first !== "object") {
753
+ return undefined;
754
+ }
755
+ if (typeof first.text === "string") {
756
+ if (/(^|[/+])json(\s*;|$)/i.test(String(first.mimeType || ""))) {
757
+ try {
758
+ return JSON.parse(first.text);
759
+ } catch (_) {}
760
+ }
761
+ return first.text;
762
+ }
763
+ return typeof first.blob === "string" ? first.blob : undefined;
764
+ };
765
+ const staleOf = (result) => Boolean(result && result._meta && result._meta["porthole/stale"] === true);
766
+ const later = (error) => setTimeout(() => {
767
+ throw error;
768
+ });
769
+ if (declared("readData")) {
770
+ lock(window, "readData", (uri) => request("resources/read", { uri: String(uri) }).then(valueOf));
771
+ }
772
+ if (declared("subscribeData")) {
773
+ // One subscription per URI, however many follow it; a read at a time, one more if it changed
774
+ // meanwhile; a late follower gets the last value at once.
775
+ const followed = new Map();
776
+ const tell = (entry, result) => {
777
+ entry.last = result;
778
+ const value = valueOf(result);
779
+ const info = { stale: staleOf(result), uri: entry.uri };
780
+ for (const listener of Array.from(entry.listeners)) {
781
+ try {
782
+ listener.onData(value, info);
783
+ } catch (error) {
784
+ later(error);
785
+ }
786
+ }
787
+ };
788
+ const fail = (entry, error) => {
789
+ for (const listener of Array.from(entry.listeners)) {
790
+ if (typeof listener.onError === "function") {
791
+ try {
792
+ listener.onError(error);
793
+ } catch (thrown) {
794
+ later(thrown);
795
+ }
796
+ }
797
+ }
798
+ };
799
+ const refresh = (entry) => {
800
+ if (entry.reading) {
801
+ entry.again = true;
802
+ return;
803
+ }
804
+ entry.reading = true;
805
+ request("resources/read", { uri: entry.uri })
806
+ .then((result) => {
807
+ if (followed.get(entry.uri) === entry) {
808
+ tell(entry, result);
809
+ }
810
+ }, (error) => fail(entry, error))
811
+ .then(() => {
812
+ entry.reading = false;
813
+ if (entry.again && followed.get(entry.uri) === entry) {
814
+ entry.again = false;
815
+ refresh(entry);
816
+ }
817
+ });
818
+ };
819
+ resourceUpdated = (uri) => {
820
+ const entry = followed.get(uri);
821
+ if (entry !== undefined) {
822
+ refresh(entry);
823
+ }
824
+ };
825
+ lock(window, "subscribeData", (uri, onData, onError) => {
826
+ if (typeof onData !== "function") {
827
+ throw new TypeError("subscribeData(uri, onData, onError): onData must be a function");
828
+ }
829
+ const key = String(uri);
830
+ const listener = { onData, onError };
831
+ let entry = followed.get(key);
832
+ if (entry === undefined) {
833
+ const made = { uri: key, listeners: new Set(), reading: false, again: false, last: undefined };
834
+ entry = made;
835
+ followed.set(key, made);
836
+ request("resources/subscribe", { uri: key }).then(() => {
837
+ if (followed.get(key) === made) {
838
+ refresh(made);
839
+ }
840
+ }, (error) => {
841
+ if (followed.get(key) === made) {
842
+ followed.delete(key);
843
+ }
844
+ fail(made, error);
845
+ });
846
+ } else if (entry.last !== undefined) {
847
+ const known = entry;
848
+ Promise.resolve().then(() => {
849
+ if (known.listeners.has(listener)) {
850
+ try {
851
+ onData(valueOf(known.last), { stale: staleOf(known.last), uri: key });
852
+ } catch (error) {
853
+ later(error);
854
+ }
855
+ }
856
+ });
857
+ }
858
+ entry.listeners.add(listener);
859
+ const mine = entry;
860
+ return () => {
861
+ if (!mine.listeners.delete(listener) || mine.listeners.size > 0) {
862
+ return;
863
+ }
864
+ if (followed.get(key) === mine) {
865
+ followed.delete(key);
866
+ request("resources/unsubscribe", { uri: key }).catch(() => {});
867
+ }
868
+ };
869
+ });
870
+ }
871
+
713
872
  window.addEventListener("error", (event) => {
714
873
  const error = event.error;
715
874
  const where = event.lineno ? " (line " + event.lineno + ")" : "";
@@ -879,6 +1038,11 @@ export const SHELL_RUNTIME = String.raw`(() => {
879
1038
  case "ui/notifications/host-context-changed":
880
1039
  applyTheme(params);
881
1040
  break;
1041
+ case "notifications/resources/updated":
1042
+ if (typeof params.uri === "string") {
1043
+ resourceUpdated(params.uri);
1044
+ }
1045
+ break;
882
1046
  case "ui/resource-teardown":
883
1047
  case "ping":
884
1048
  if (data.id !== undefined) {