From 5b6456a7cab063cde4f695d275630556f513abad Mon Sep 17 00:00:00 2001
From: jrandolf <101637635+jrandolf@users.noreply.github.com>
Date: Tue, 13 Feb 2024 12:09:30 +0100
Subject: [PATCH] chore: add README to `bidi/core` (#11882)

---
 packages/puppeteer-core/.gitignore            |  2 +-
 .../puppeteer-core/src/bidi/core/README.md    | 57 +++++++++++++++++++
 2 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 packages/puppeteer-core/src/bidi/core/README.md

diff --git a/packages/puppeteer-core/.gitignore b/packages/puppeteer-core/.gitignore
index 42061c01a1c..3d32a7ba827 100644
--- a/packages/puppeteer-core/.gitignore
+++ b/packages/puppeteer-core/.gitignore
@@ -1 +1 @@
-README.md
\ No newline at end of file
+/README.md
\ No newline at end of file
diff --git a/packages/puppeteer-core/src/bidi/core/README.md b/packages/puppeteer-core/src/bidi/core/README.md
new file mode 100644
index 00000000000..5b5456aadbb
--- /dev/null
+++ b/packages/puppeteer-core/src/bidi/core/README.md
@@ -0,0 +1,57 @@
+# `bidi/core`
+
+`bidi/core` is a low-level layer that sits above the WebDriver BiDi transport to
+provide a structured API to WebDriver BiDi's flat API. In particular,
+`bidi/core` provides object-oriented semantics around WebDriver BiDi resources
+and automatically carries out the correct order of events in WebDriver BiDi through
+the use of events.
+
+## Tips
+
+There are a few design decisions in this library that should be considered when
+developing `bidi/core`:
+
+- Required arguments are inlined as function arguments while optional arguments
+  are put into an options object.
+
+  - Function arguments are implicitly required in TypeScript, so by putting
+    required arguments as function arguments, the semantic is automatically
+    inherited.
+
+- The session shall never be exposed on any public method/getter on any
+  object except the browser. Private getters are allowed.
+
+  - Passing around the session is dangerous as it obfuscates the origin of the
+    session. By only allowing it on the browser, the origin is well-defined.
+
+- `bidi/core` implements WebDriver BiDi plus its surrounding specifications.
+
+  - A lot of WebDriver BiDi is not strictly written in WebDriver BiDi. Since WebDriver
+    BiDi interacts with several other specs, there are other considerations that
+    also influence the design of `bidi/core`. For example, for navigation,
+    WebDriver BiDi doesn't have a concept of "nested navigation", but in
+    practice this exists if a fragment navigation happens in a `beforeunload`
+    hook.
+
+- `bidi/core` always follow the spec and never Puppeteer's needs.
+
+  - By ensuring `bidi/core` follows the spec rather than Puppeteer's needs, we
+    can identify the source of a bug precisely (i.e. whether the spec needs to
+    be updated or Puppeteer needs to work around it).
+
+- `bidi/core` attempts to implement WebDriver BiDi comprehensively, but
+  minimally.
+
+  - Imagine the objects and events in WebDriver BiDi as a large
+    [graph](<https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)>) where
+    objects are nodes and events are edges. In `bidi/core`, we always implement
+    all edges and nodes required by a feature without skipping nodes and events
+    (e.g. [fragment navigation -> navigation -> browsing context]; not [fragment
+    navigation -> browsing context]). We also never compose edges (e.g. both
+    [fragment navigation -> navigation -> browsing context] and [fragment
+    navigation -> browsing context] must not exist; i.e. a fragment navigation
+    event should not occur on the browsing context). This ensures that the
+    semantics of WebDriver BiDi is carried out correctly.
+
+  - This point reinforces `bidi/core` should not follow Puppeteer's needs since
+    Puppeteer typically composes a lot of events to satisfy its needs.