Docs: Update architecture documentation.

1 files changed, 76 insertions, 3 deletions

diff --git a/docs/architecture.md b/docs/architecture.md
index 7c5b091..26232c9 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -15,6 +15,7 @@ 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.
+*   `LibNSLog` for logging.
 
 Interface
 ---------
@@ -79,7 +80,7 @@ will:
 3.  Try to fit as many non-breakable sections on a line as possible, given
     the available width.
 
-Note that some breaks may not be permissable, since they will fall inside
+Note that some breaks may not be permissible, since they will fall inside
 inline elements which are styled to prevent wrap.  Also, to measure each
 non-breakable section, there may be multiple calls to the client to measure
 sub-sections of the non-breakable section according to different parts of the
@@ -87,6 +88,78 @@ text having different styles.  We can probably avoid this depending on which
 CSS properties are different.  (e.g. `color` and `text-decoration` won't affect
 text measurement.)
 
-> **TODO**
+> **TODO**: How to do justified text?
 > 
-> 1.  How to do justified text?
+> Probably we can measure the minimum space width needed on a line,
+> fit as much text as possible with that, and share any remaining space
+> out over each break-point that is a space.
+
+### Layout
+
+Layout will be lazy, and only actually done when prompted by the client.
+The client will be getting DOM modification events and informing LibNSLayout.
+LibNSLayout will be notified when elements are added and removed from the
+DOM, and when TEXT nodes are added/modified/removed.
+
+> **TODO**: How lazy to be?
+> 
+> We could either:
+> 
+> 1.  Build/update layout tree as we get the updates (but not performing
+>     layout until asked by the client).
+> 2.  Queue DOM update events and elide updates that cancel themselves out.
+>     For example if an element is added and immediately removed, there is
+>     no point in doing anything.  (Or is there?  Consider starting fetches
+>     as early as possible.)  We would then only update the layout tree when
+>     the queue gets too long or when the client requires a layout.
+
+If an element is added, we would perform CSS selection, and assuming its not
+got `display: none` we'd add the elements entry in the layout tree.  When we
+add the new entry to the layout tree, we'd mark its parents as needing layout.
+We'd keep walking up the ancestor chain marking as needing layout until we hit
+a layout entry who's width and height are fixed, meaning it can't affect its
+parent layout.
+
+When the client requires a layout, we would then walk the tree, ensuring every
+layout node has a valid `x`, `y`, `width`, and `height`.
+
+### Rendering
+
+The client is responsible for rendering, and any compositing.  When the
+client asks LibNSLayout to layout, LibNSLayout returns a render list.
+
+> **TODO**: Details?
+>
+> 1.  Consider render list optimisation (e.g. NetSurf's Knockout rendering).
+> 2.  What will the render list look like.
+
+### Fetches
+
+There are several kinds of fetches to consider:
+
+*   Fetch resources directly required by the document.  (Client initiated.)
+    *   CSS
+    *   JavaScript
+    *   Images
+    *   Iframes
+    *   etc...
+*   Fetch resources required by element computed styles.  (LibNSLayout
+    initiated.)
+    *   Background images.
+    *   Web fonts.
+
+For a client initiated fetch of CSS, the selection context is updated when
+we have fetched the style sheet, and LibNSLog is informed.
+
+For a LibNSLayout initiated fetch, LibNSLayout creates a `nsl_resource_t`
+and passes a pointer to to to the client, along with the URL to fetch.
+The `nsl_resource_t` is opaque to the client.  When the resource is fetched,
+the client calls a callback passing, the `nsl_resource_t`, and a pointer to
+the client handle for the resource (`hlcache_handle`, in NetSurf).  Then
+`LibNSLayout` can set the pointer to the client resource handle inside the
+`nsl_resource_t`, and the pointer will be used to ask the client about e.g.
+intrinsic dimensions.  The pointer to the client handle will also appear in
+the render list that is given to the client for display.
+
+> **TODO**: How to do fetches started by client for e.g. images, that
+> LibNSLayout needs to know about.