Skip to content

Track output-level dependencies for correct granular watch rebuilds #289

Closed

Description

@bcomnes

Problem

A targeted source-page rebuild recalculates global.data, but only writes the directly affected page. Other rendered pages, templates, and generated pages can consume values derived from the changed page and remain stale.

This was reproduced with two Markdown pages and a global.data.js value derived from all page titles. After changing one title, that page received the new collection value while the other page retained the old value.

The invalidation rule needs to account for:

  • Rendered pages consuming values returned by global.data.
  • Templates consuming source pages, generated pages, or global data.
  • Generated-pages factories consuming source pages or global data.
  • Layouts inspecting the complete page collection.
  • readMarkdownContent(), renderInnerPage(), and renderFullPage() creating content dependencies between outputs.

A blanket rebuild would preserve correctness but defeat granular watch builds, particularly because templates and generated pages are often the largest collection consumers.

Proposed direction

Persist an output-level dependency graph from successful watch renders:

  • Give source pages, generated-page owners, templates, and rendered outputs stable identities.
  • Track reads from page vars, page metadata, render helpers, and top-level global.data keys.
  • Attribute concurrent reads to the active consumer.
  • Fingerprint observed values and invalidate only consumers whose observed values changed.
  • Send plain dependency records from the page worker to the main DomStack instance through the existing worker result.
  • Fall back conservatively for opaque values and render-helper calls.
  • Add an explicit invalidation API for file, environment, network, or other external reads DOMStack cannot observe.

Array iteration should record collection membership/order dependencies, while reads from individual PageData values should remain page-specific.

Acceptance criteria

  • A changed page updates rendered pages, templates, and generated outputs that observed its changed values.
  • Consumers of unchanged page properties or unchanged global-data keys do not rebuild.
  • Dependency records are replaced only after a successful consumer build.
  • Dependency tracking is scoped to watch mode and does not alter one-shot production builds.
  • Dependency-driven generated-page renames remove obsolete outputs.
  • Concurrent renders attribute reads to the correct consumer.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions