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, appropriate CSS media descriptor, and scale.
*   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.
*   Passing scale changes to LibNSLayout.
*   Performing measurement of text; given a string & style, calculating its
    width in pixels.

### 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.
*   Asking client to measure text.
*   Performs line breaking.
*   Performs layout (if required) when asked by client and returns render list.
*   Performs layout (if required) when asked by client for layout info.

Details
-------

### Text layout

LibNSLayout is responsible for performing line-breaking.  It uses a third
party library ([libunibreak](https://github.com/adah1972/libunibreak)) to
provide the Unicode line breaking algorithm implementation.  LibNSLayout
will:

1.  Pass the text of a paragraph to the `libunibreak` and get back a list of
    possible break points.
2.  Ask the client to measure each non-breakable section.
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
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
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**
> 
> 1.  How to do justified text?