Documentation: Start documenting library architecture.

1 files changed, 60 insertions, 0 deletions

diff --git a/docs/architecture.md b/docs/architecture.md
new file mode 100644
index 0000000..c45d355
--- /dev/null
+++ b/docs/architecture.md
@@ -0,0 +1,60 @@
+LibNSLayout Architecture
+========================
+
+`LibNSLayout` is a library for performing layout on a Document Object Model
+for HTML.  Its purpose is to allow client applications to provide DOM
+information and convert that into a render list, which can be displayed
+by the client.
+
+Dependencies
+------------
+
+Clients of `LibNSLayout` must use the following additional libraries, because
+their types are used in the `LibNSLayout` interface:
+
+*   `LibDOM` is used to provide the DOM interface.
+*   `LibCSS` is used to provide the CSS handling.
+*   `LibWapcaplet` is used for interned strings.
+
+Interface
+---------
+
+The devision of responsibilities between `LibNSLayout` and its clients are
+as follows:
+
+### Client
+
+*   Fetching the document to be displayed.
+*   Creating a CSS selection context (with default user-agent, and user CSS).
+*   Generating DOM.
+*   Creating a `LibNSLayout` layout for the document, passing the DOM document,
+    CSS selection context, and appropriate CSS media descriptor.
+*   Listening to DOM changes.
+    *   Fetching resources needed by DOM.
+        *   CSS (STYLE elements, and LINK elements):
+            *   Parsing the CSS.
+            *   Updating CSS selection context as stylesheets are fetched,
+                and notifying `LibNSLayout`.
+        *   JavaScript (SCRIPT elements, and LINK elements)
+            *   Executing JavaScript.
+        *   Favicons (LINK elements.)
+        *   Images, Frames, Iframes.
+    *   Notifying `LibNSLayout` of DOM changes.
+*   Performing resource fetches on behalf of LibNSLayout.
+    *   (Such as when LibNSLayout requires a background image or web font for
+        an element due to CSS.)
+*   Asking `LibNSLayout` to perform layout.
+    *   Displaying the returned render list.
+*   Asking `LibNSLayout` for layout info (e.g. due to JavaScript.)
+*   Passing mouse actions to `LibNSLayout`.
+*   Passing keyboard input to `LibNSLayout`.
+*   Measuring text???
+
+### `LibNSlayout`
+
+*   Creates a layout object that's opaque to the client, and returns its
+    handle.
+*   Performs CSS selection as appropriate when DOM changes.
+*   Asking client to fetch a resource that's needed for a computed style.
+*   Performs layout (if required) when asked by client and returns render list.
+*   Performs layout (if required) when asked by client for layout info.