[v2]: cursor based chore handling

[wmertens]

Qwik Cursors Architectural Document

This document outlines some core architectural concepts of Qwik, specifically focusing on its sparse virtual DOM (vDOM) implementation, chore execution mechanism, and cursor management for both server-side rendering (SSR) and browser environments.

1. Sparse Virtual DOM (vDOM)

Qwik utilizes a sparse vDOM, which represents only the DOM nodes that are of interest (i.e., potentially mutable). This contrasts with traditional vDOM implementations that often represent the entire tree.

1.1. vNode Structure

Each node in the sparse vDOM is represented by a vNode. A vNode has the following key properties:

• type: string | Function: Can be either a string representing an HTML tag name (e.g., 'div', 'span') or a function representing a inline component or a Qwik component.
• varProps: Props: An object containing properties that can change during the vNode's lifetime (e.g., attributes, styles).
• constProps: Props: An object containing properties that cannot change after the vNode is created. Meaning, scalar values won't change, and references to objects are immutable but their internal state can change. If these objects are reactive, they can still trigger DOM attribute updates.
• qKey: string: A unique identifier for the vNode within its parent, used for efficient tracking and updates.
• parent: vNode | null: A reference to the parent vNode in the tree.
• children: vNode[]: An array of child vNodes.
• depth: number: The depth of the vNode in the tree, including any skipped nodes. This can be used for ancestry detection.
• sequentialScope: unknown[] | null: An array used to store the state of component hooks (e.g., useTask$).
• dirty: number: A bitfield used to indicate which chores need to be performed on this vNode.
• jsxOutput: JSXOutput | null: Stores the result of rendering the component's JSX, used during the NODE_DIFF chore.
• dirtyChildren: Set<VNode> | null: A set containing child vNodes that are currently marked dirty.

1.2. vNode Types

• VNode: The base class for all vNodes.
• SsrVNode: Inherits from VNode and adds streamed: boolean to indicate if the opening tag for this node has begun streaming during SSR.
• DomVNode: Inherits from VNode and adds element: Element | null to store a reference to the actual DOM element it represents in the browser.

2. Chore Execution Mechanism

Qwik uses a chore-based system to manage updates to the vDOM and the DOM. Chores represent specific tasks that need to be performed on a vNode. Chores are indicated by the dirty bitfield.

2.1. Chore Order

Chores are executed in a specific order:

• TASK: Runs any dirty useTask$ callbacks attached to the vNode's sequentialScope. These tasks are render-blocking by default, meaning they must complete before further rendering can proceed.
• NODE_DIFF:
  • Compares the vNode with the stored jsxOutput.
  • Updates the vNode's structure (children, props) to match the new jsxOutput.
  • Records changes in a journal (only for DOM environments).
  • Creates, updates, or deletes child vNodes as needed.
  • Marks child vNodes as dirty if necessary.
  • Awaits any Promise encountered during the process.
• NODE_PROP: Applies changed properties from the vNode's varProps to the corresponding DOM element (only for DOM environments). This does not block children processing, but is blocked by parent processing and is therefore a chore.
• COMPONENT:
  • Executes the component function (type(props)).
  • Awaits any Promise returned by the component function.
  • Marks the vNode for NODE_DIFF with the result stored in jsxOutput.
• RECOMPUTE_AND_SCHEDULE_EFFECTS:
  • Calculates any dirty computed signals attached to the vNode's sequentialScope.
  • Does not await the results of these calculations.
  • If a computed signal has changed, it itsel schedules appropriate chores based on its stored effects.

2.2. Chore Execution Rules

• Chores must be executed in the specified order (TASK, NODE_DIFF, NODE_PROP, COMPONENT, RECOMPUTE_AND_SCHEDULE_EFFECTS).
• Child vNodes can only be processed if their parent vNode is currently clean (i.e., all its chores have been completed).

2.3. Efficient Dirty Marking

• When a chore needs to be performed on a vNode, it is marked dirty by setting the corresponding bit in the dirty bitfield.
• The vNode is also added to its parent's dirtyChildren set.
• When a vNode becomes clean (all its chores completed), it removes itself from its parent's dirtyChildren set.
• When a child vNode is marked dirty, this dirty status is propagated upwards to the topmost ancestor vNode that is already dirty.
• If no ancestor is dirty, the current vNode receives a cursor.

3. Cursors

A cursor is a reference to a vNode that enables efficient traversal and manipulation of the vDOM tree. It has a low or high priority.

3.1. Cursor Lifecycle

• A cursor always indicates the topmost dirty vNode in its subtree, except where it was created recursively.
• Processing a cursor involves executing the dirty chores of the referenced vNode in the defined order.
• Once all chores for the current vNode are complete, its dirtyChildren (if any) are processed.
• If a child vNode returns a Promise during processing (e.g., during NODE_DIFF or COMPONENT), a new cursor is created for that child (using the same journal in DOM environments), it is removed from the dirtyChildren set, and processing continues with the next sibling.
• A cursor is considered done when all its chores and those of all its children (excluding any recursively created cursors) have been completed.

3.2. Cursor Propagation

• If a chore causes an ancestor vNode to become dirty (except for NODE_PROP chores), all active cursors under that ancestor are stopped. These stops are awaited and if they are not done, their intermediate vNodes are added to the dirtyChildren set of their respective parents.
• The ancestor vNode then receives a new cursor.

3.3. Parallel Processing

• Whenever a change occurs in the vDOM, one or more top-level cursors are created.
• These top-level cursors are then processed in parallel.
• Processing pauses every 16ms to yield control back to the main thread, ensuring responsiveness.
• Idle time is when there are no high-priority cursors to process.
• Cursors that start on DOM nodes that are not currently visible get a lower priority so visible changes happen faster. This means that their chores are only processed when there is idle time or when they hit a deadline.

4. Environment-Specific Considerations

4.1. DOM Environment

• A journal is used to store the changes to be applied to the DOM during the NODE_DIFF and NODE_PROP chores.
• The journal is committed to the DOM only when a cursor is done (i.e., all its chores and those of its children are complete).
• When committing the journal, changes must be sorted by vNode depth (deepest first) to ensure that deletions can skip journal entries corresponding to nodes below the deleted node.

4.2. Server-Side Rendering (SSR) Environment

• No journal is used in SSR.
• The HTML output is streamed directly to the client as chores are executed.
• Streaming can be paused, particularly when encountering Suspense boundaries. This means that there is a single reference to the currently streaming vNode.
• During a streaming pause, child vNodes can cause parent vNodes to change without error, as long as they didn't begin streaming yet.
• The use of multiple cursors enables efficient parallel waiting for multiple asynchronous children during streaming.
• If a Suspense boundary is encountered and the first Promise within it takes longer than a timeout to resolve, an out-of-order vNode (e.g., a placeholder) is created and included in the initial HTML stream. This out-of-order node will be filled in later when the Promise resolves.
• Streaming resumes once the cursors associated with a Suspense boundary are done or when the OoO node is streamed.

[wmertens]

Additional things:

• when marking a vnode dirty, you should look up parents until the depth of the highest cursor. If you encounter a cursor or dirty parent, mark all parents in between dirty. Otherwise it's a new cursor
• projected children must go into the dirtySet of their slot parent.
  • if the slotparent is gone, put them in a separate set of slow dirty vnodes?
• when running the component function, the return value is awaited and then node_diff is done. no need to store the jsxoutput. The child vnodes will get their new props and children so no need there either
• (maybe) the container root is just another vNode, no parent. It starts dirty and its function returns the container tag with the props, and the children. That way no diff task?

[wmertens]

Implementation:

• add dirty and dirtyChildren to VNode
• implement dirty propagation of vnodes including cursor creation
• implement invalidation-makes-host-dirty for tasks, computed signals etc
• implement cursor iteration

optimizations:

• add depth to vnodes, so existing cursor scanning can stop at the highest cursor depth
• add static and staticTree flags to string tags that only have scalar constProps, so they don't create vnodes