Documentation for HTML Model element (take 2)

[zachernuk]

( This is a rebuild of the Model element PR from #39710 )

Preface to the new PR

This branch is a clean rebuild of the substantive content about the HTML Model element from the earlier PR at #39710
where I had alterations to a .lock file. Since I'm not familiar enough with Git to revert one single file in the overall process, I thought it would be best to start fresh. Apologies for the clutter!

Description

This PR adds API documentation about the proposed HTML Model element, a browser-native feature for the in-line display of 3D content. It includes illustrations of some core concepts like perspective, lighting and appropriate file formats.

Motivation

The Model element is a totally new web feature and it'll be exceptionally difficult to add documentation in a piecemeal fashion. I'm hoping that this covers the core concepts enough to author new pages from, and matches the MDN house style well enough that other folks can improve them to the point that they are real!

Additional details

I am submitting provisional documentation for the HTML model element, a feature that is the major source of discussion in the W3C Immersive Web CG (https://github.com/immersive-web/model-element/ )
and which is available as a feature preview in visionOS 2.4. I am an editor of the specification and have been facilitating the discussion around it.

While the specification doesn’t have a lot of detail, the API in visionOS is based on the consensus discussion in the CG, and is described in the Model Element explainer: (https://github.com/immersive-web/model-element/blob/main/explainer.md )

There is also a WebGL/WebXR-based interactive explainer demo available here:
https://immersive-web.github.io/model-element/explainer_demo.html

We also have public samples being contributed by multiple browser vendors in the model element samples repository.
https://immersive-web.github.io/model-element-samples/

We have previously submitted related additions to the WHATWG HTML specification as via an introductory issue and initial PR for the specification stub.
whatwg/html#10901
whatwg/html#11191

Related issues and pull requests

WHATWG/HTML

• Display of an inline 3D model whatwg/html#10901
• new model element for display of inline 3D models whatwg/html#11191

the Web Platform Tests repository

• Initial Model element tests web-platform-tests/wpt#51667

HTML-ARIA

• New in-line 3D HTML model element w3c/aria#2508

[github-actions]

Preview URLs (20 pages)

• /en-US/docs/Web/API/HTMLModelElement/autoplay
• /en-US/docs/Web/API/HTMLModelElement/boundingBoxCenter
• /en-US/docs/Web/API/HTMLModelElement/boundingBoxExtents
• /en-US/docs/Web/API/HTMLModelElement/currentSrc
• /en-US/docs/Web/API/HTMLModelElement/currentTime
• /en-US/docs/Web/API/HTMLModelElement/duration
• /en-US/docs/Web/API/HTMLModelElement/entityTransform
• /en-US/docs/Web/API/HTMLModelElement/environmentMapReady
• /en-US/docs/Web/API/HTMLModelElement/environmentMap
• /en-US/docs/Web/API/HTMLModelElement/height
• /en-US/docs/Web/API/HTMLModelElement/loop
• /en-US/docs/Web/API/HTMLModelElement/pause
• /en-US/docs/Web/API/HTMLModelElement/paused
• /en-US/docs/Web/API/HTMLModelElement/play
• /en-US/docs/Web/API/HTMLModelElement/playbackRate
• /en-US/docs/Web/API/HTMLModelElement/ready
• /en-US/docs/Web/API/HTMLModelElement/stageMode
• /en-US/docs/Web/API/HTMLModelElement/width
• /en-US/docs/Web/API/HTMLModelElement
• /en-US/docs/Web/HTML/Reference/Elements/model

Flaws (1)

Note! 19 documents with no flaws that don't need to be listed. 🎉

URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element
Flaw count: 1

• broken_links:
  • Can't resolve /en-US/docs/Web/Accessibility/ARIA/Reference/Roles/model_role

External URLs (13)

URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxCenter
Title: HTMLModelElement: boundingBoxCenter property

• https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/HTMLModelElement/boundingBoxExtents
Title: HTMLModelElement: boundingBoxExtents property

• https://en.wikipedia.org/wiki/Center_of_mass (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Skeletal_animation (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/HTMLModelElement/environmentMap
Title: HTMLModelElement: environmentMap property

• https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/API/HTMLModelElement/playbackRate
Title: HTMLModelElement: playbackRate property

• https://en.wikipedia.org/wiki/Double-precision_floating-point_format (1 time) (Note! This may be a new URL 👀)

---

URL: /en-US/docs/Web/HTML/Reference/Elements/model
Title: <model>: The HTML Model element

• https://en.wikipedia.org/wiki/Cartesian_coordinate_system (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Equirectangular_projection (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/Identity_matrix (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/OpenEXR (1 time) (Note! This may be a new URL 👀)
• https://en.wikipedia.org/wiki/RGBE_image_format (1 time) (Note! This may be a new URL 👀)
• https://openusd.org/release/spec_usdz.html (1 time) (Note! This may be a new URL 👀)
• https://www.khronos.org/gltf/ (1 time) (Note! This may be a new URL 👀)

[wbamberg]

I've talked about this PR with some of the other MDN maintainers, and we don't think this feature is ready to be documented on MDN yet (and therefore isn't ready for a review yet). We use two main criteria for deciding when a feature is ready: the extent to which it's implemented in browsers, and the extent to which there's a stable, detailed, specification for it.

The key place these criteria are described is https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/What_we_write#when_we_document_a_new_technology . In particular, this lists the following as a reason not to document a feature:

It doesn't have a specification or the specification is a rough note that looks liable to change,

This seems applicable to the spec as it stands: https://immersive-web.github.io/model-element/. I know the PR description here says:

While the specification doesn’t have a lot of detail, the API in visionOS is based on the consensus discussion in the CG, and is described in the Model Element explainer: (https://github.com/immersive-web/model-element/blob/main/explainer.md )

...but the explainer is also not detailed enough to function as a spec.

It's my understanding that this is shipping in a technical preview of VisionOS. AFAIK only shipping in a technical preview doesn't count as "shipping" for our purposes, because it doesn't represent evidence that the feature is stable.

The underlying reason for these criteria is that we don't want to document things that are likely to change a lot or potentially not be adopted at all. When we document things too early, one of these things happens quite often.

I think the best plan would be to mark this PR a draft, and continue to update it as the specification matures, and ask for a review when the specification is stable and it is shipping.

[zachernuk]

Thank you for the reasoned response, @wbamberg. I’ll aim to revisit this if/when a browser releases the feature and we have a better basis to reason about what the spec needs to clarify.

[zachernuk]

HTML Model element is now available by default in visionOS 26! Now that more folks will actually be able to see it, I believe we'll be able to start negotiating and filling out specification-class descriptions for multiple vendors to agree on.

@wbamberg I'm open to your recommendations as to whether we add detail to MDN piecemeal, as it's added to a spec, or if we can provide the current state as-is and revise/refine once other vendors are in a position to help us define mandatory algorithm structures etc.

[wbamberg]

@wbamberg I'm open to your recommendations as to whether we add detail to MDN piecemeal, as it's added to a spec, or if we can provide the current state as-is and revise/refine once other vendors are in a position to help us define mandatory algorithm structures etc.

I think it makes sense to wait until the specification is stable and detailed and then file a PR to document the whole thing.