StrictDoc

Every editable field follows a standard request/response lifecycle using Turbo Streams:

1. GET (Fetch Form): Clicking a display triggers a GET request to the URL in the field's data-url (e.g., get_node_contenteditable_inline, get_node_autocomplete_inline, etc.). The request must include Accept: text/vnd.turbo-stream.html (TURBO_ACCEPT).
2. Turbo Stream (Swap): The server returns a Turbo Stream that swaps the field's display content for an editable form, scoped to the target ID (e.g., <div id="cell-{mid}-{FIELD}"> or <div id="doc-field-{mid}-{FIELD}">).
3. POST (Save): On blur, outside click, or Ctrl/Cmd+Enter, the JS serializes and POSTs the form to the matching update endpoint (e.g., update_node_field, update_node_comments, update_document_custom_meta).
4. Turbo Stream (Result):
   • Success: A Turbo Stream re-renders the field's display.
   • Validation Error: A Turbo Stream re-renders the active field along with sdoc-form-error markers.

StrictDoc uses a stateful viewport controller (content_viewport_restoration.js) to prevent visual jumps (layout shifts) when the document geometry changes due to lazy loading, content replacement, or resizing.

Instead of tracking raw pixel offsets, the controller uses semantic viewport snapshots. A snapshot identifies a witness (a meaningful document element, preferably a visible sdoc-node) and its position. When the DOM changes, the controller finds the same witness in the new DOM and adjusts .main.scrollTop to compensate for the movement.

The Restoration Sequence:

1. Record: Before DOM changes, capture a semantic viewport snapshot (the witness and its position relative to .main).
2. Mutate: Allow the DOM mutation (e.g., Turbo rendering a chunk) to occur.
3. Locate: Find the same semantic element in the updated DOM.
4. Measure: Calculate how far the element moved relative to .main.
5. Compensate: Adjust .main.scrollTop by the exact difference.
6. Protect: Continue protecting this position through subsequent asynchronous changes (like placeholder height removals) using a generation system to ignore obsolete updates.

The controller must manage viewport stability during the following events:

• Lazy Loading: When a lazy placeholder is replaced with rendered nodes, or when an estimated height for a placeholder is removed.
• Document Replacement: When the complete frame_document_content DOM is replaced following a server operation, or when the replacement introduces new lazy placeholders.
• Content Mutation: When content that has already been inserted changes height, or when a user creates, deletes, moves, or edits document content.
• Non-chunked Operations: When the same server operations are performed on a document that is not chunked.

Note on User Intent: The controller must respect newer user intent. If a user scrolls or navigates after a position was recorded, the controller must not allow an older asynchronous callback to return the viewport to the previously recorded position.

StrictDoc uses a single Jinja template (strictdoc/export/html/templates/_shared/favicon.svg.jinja) to render different favicon variants based on the execution environment. This allows the favicon to adapt to development, testing, or production/export modes, as well as the user's light/dark color scheme.

Environment Mapping

The variant is determined by the following logic:

• test: Set when STRICTDOC_ENV=test is present (used by SDocTestServer).
• dev: Set when the --development CLI flag is used (e.g., via invoke server).
• export: Set when running a static strictdoc export or HTML2PDF export.
• default: The fallback for a standard, live, non-dev, non-test server.

Technical Details

• Color Adaptation: Each variant defines its own light_color and dark_color pairs used via @media (prefers-color-scheme: light/dark).
• Rendering Lifecycle: The favicon is rendered once per process by HTMLGenerator.export_assets() and written to _static/favicon.svg, overwriting any existing static file. It is served as a plain file from disk.
• Testing: The root <svg> includes data-testid="{{ variant }}-favicon" to allow unit tests to verify the rendered variant without relying on color values.

The Tree Map uses a split architecture between Python and the Browser to handle complex project data.

Data Generation (Python)

Python is responsible for preparing the hierarchy and the StrictDoc-specific data. This design allows users to define custom logic for what a tree map displays by adding user-defined functions in Python without needing to modify the browser-side renderer.

Rendering (Browser)

The browser receives the hierarchy as a JSON object. The renderer is responsible for:

• Calculating the layout (using weight-based sizing).
• Managing visual constraints (minimum node dimensions, visibility thresholds).
• Handling synthetic groups (grouping nodes when there are too many direct children to preserve usability).
• Managing the DOM (limiting visible depth and node count for performance).

JSON Contract

The JSON data follows a specific contract:

• Labels and Counts: These are kept as separate values. The renderer exposes the count via the data-count attribute on the label element.
• Identifiers: Each serialized node must have a stable identifier.

In StrictDoc, the DOCUMENT screen must maintain visual stability for content currently in view when asynchronous rendering changes the document's geometry.

Visual stability is achieved by selecting a witness: a meaningful visible element that the controller tracks. Instead of relying on the scrollbar's numeric position (scrollTop), the controller records the witness's position relative to the .main viewport and ensures it remains at that same coordinate after geometry changes.

The Stability Requirement: witness_top_after == witness_top_before

This mechanism is necessary because:

• Lazy placeholders being replaced by real DOM nodes can have different heights than their estimates.
• Full frame_document_content DOM replacements (e.g., after server operations) invalidate previous scroll positions.
• User edits, deletions, or moves change the document structure.
• Native browser scroll anchoring is insufficient because it cannot track elements across DOM replacements or handle specific application-level logic like deletion boundaries.