feat: add useTresReady

[andretchen0]

Features

This PR adds the following features via a private composable useTresReady:

• onTresReady hook
• @ready emit from TresCanvas
• start loop onTresReady

Note

Tres is "ready" when either:

• context, renderer, and canvas exist and canvas has a height and width greater than 0.
• 100 ms has passed since TresContext was created.

Important

The 100 ms timeout above exists to keep Tres working as expected even in edge cases – like the user setting the canvas size to 0 x 0 explicitly.

Because of the timeout, it is not guaranteed that the canvas will be renderable when @ready.

Playground

pnpm run playground

... then open http://localhost:5173/basic/ready

---

Problem

useLoop calls user callbacks before THREE can actually render to the screen, e.g., in the default setup, <canvas> will have a height/width of 0 when useLoop starts.

For debugging, this means that the developer needs to wait for a few frames to pass before they get "real" values in their logs/debugger.

Solution

Start the loop and trigger ready callbacks when Tres is "ready".

Use case

DX, particularly debugging.

Problem

#572

Users had been asking for an easier way to get the context from a TresCanvas in a <script setup>. It currently requires a few steps that users find non-obvious, as outlined in the issue above.

Solution

• Add a @ready emit that takes a callback and calls it with TresContext when Tres is "ready"

<script setup>
const myFn = (ctx: TresContext) => {
  // NOTE: do something with ctx
}
</script>

<template>
  <TresCanvas @ready="myFn" />
</template>

Use case

DX. Advanced users who want to write a bit less code in order to access TresContext.

Problem

Child components can't take advantage of "ready" without registering a loop callback.

Solution

• Add onTresReady hook

<script setup>
import { onTresReady } from '@tres/core';

// NOTE: requires `TresContext`, so it can only be used in child components.
onTresReady((ctx: TresContext) => {
  // NOTE: do something with ctx
})
</script>

Use case

DX. Advanced users who want to be notified when Tres is "ready" in child components.

---

Meta

closes #595 – the present PR modifies useLoop not useRenderLoop as in the issue. But useRenderLoop is no longer Tres' preferred looping method
closes #572

[netlify]

✅ Deploy Preview for tresjs-docs ready!

Name	Link
🔨 Latest commit	6789a3b
🔍 Latest deploy log	https://app.netlify.com/sites/tresjs-docs/deploys/666d60c2f6cc8b0008ab595d
😎 Deploy Preview	https://deploy-preview-712--tresjs-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[alvarosabu]

This is great @andretchen0 thank you so much. sorry took me so long to review it , I just tested everything 💚