refactor: extract Document, Animation, and XPath interfaces

[jderochervlk]

Tracking issue: #342

Summary

• move Document methods and supporting option records into the owning Document module
• define Animation.t, animation state types, and animation methods locally
• define XPath expression and result types in their owning modules
• remove the corresponding broad aliases from DomTypes

Temporary state

• DomTypes still contains the unrelated recursive DOM, HTML, SVG, CSS, and helper types needed by later layers
• refactor: introduce DOMTree compatibility foundation #301 introduces the bridge for migrating those recursive interfaces; refactor: remove DOM compatibility types #310 completes the migration and deletes DomTypes
• final source-folder ownership remains follow-up Option 5 work

Review focus

• the extracted Document, Animation, and XPath signatures
• public API continuity while removing their DomTypes aliases

Verification

• npm run build
• npm test
• npm run format:check

[brnrdog]

I liked the types living within their interfaces, makes them much more discoverable than before with the DOMTypes. I think the DOMTree is fair given the recursive types.

I'm just missing a .t for Element/Node/HTMLElement, like we do for other modules. What if we add a small alias on each like:

type t = DOMTree.element
include Impl({type t = t})

[jderochervlk]

I liked the types living within their interfaces, makes them much more discoverable than before with the DOMTypes. I think the DOMTree is fair given the recursive types.

I'm just missing a .t for Element/Node/HTMLElement, like we do for other modules. What if we add a small alias on each like:

type t = DOMTree.element
include Impl({type t = t})

Yeah, I think having a type t on modules makes sense and I do like it. I'll make sure those get added in.

[jderochervlk]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2e9ab9f34c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[fhammerschmidt]

can we add comments to explain this and the other empty record types?
not necessarily in this PR

[jderochervlk]

Tracking the documentation audit for these intentionally empty types in the parent issue follow-up checklist.

[fhammerschmidt]

also worth a discussion whether animationTimeline should be just timeline now that it resides in a dedicated Animation module.

[jderochervlk]

Tracking this naming decision in the parent issue follow-up checklist.

[jderochervlk]

The .t alias follow-up from this review is now tracked in the parent issue follow-up checklist.