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[bot]]

✅ Deploy Preview for tresjs-docs ready!

Name	Link
🔨 Latest commit	6789a3b169b18a0eea9520a6a25382f8fb67ba34
🔍 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.