@solidrt/core 0.0.60 → 0.0.62

package/src/window.ts

@@ -2,7 +2,7 @@ import { createSignal, getOwner, onCleanup, onSettled, runWithOwner, flush } fro
 import { requestFrame, setPointerLock } from "flux:rendertree"
 import { renderFrame } from "srt:render"
 import { on, once } from "srt:events"
-import { exit as nativeExit, background as nativeBackground } from "srt:app"
+import { exit as nativeExit, background as nativeBackground, registerProtocolHandler as nativeRegisterProtocolHandler } from "srt:app"
 import { platform } from "flux:process"
 import { getEventHandler, focusedNode, setFocus, activateTextInput, setInterestRoot } from "./core"
 import { scanForOrphans, getNodePath } from "./renderer"
@@ -141,6 +141,20 @@ export function background() {
   nativeBackground()
 }
 
+/**
+ * Makes this install the handler for the app's own scheme, so links like
+ * `com.example.app://settings` (the scheme is the appId) open the app from a
+ * browser, another app or the shell: `env.launchLink` when it starts the
+ * app, `onLink` when the app already runs. The web's name, simplified: no
+ * arguments, the scheme is fixed. A packed desktop app has to call it,
+ * since nothing installs a single executable (call it again after moving
+ * the executable); Android and macOS packages declare the scheme, so the
+ * call does nothing there. Throws when the registration cannot be written.
+ */
+export function registerProtocolHandler() {
+  nativeRegisterProtocolHandler()
+}
+
 // The default action of an unprevented back event: what the platform itself
 // does at the root of an app. Android backgrounds (since Android 12);
 // everywhere else back at the root ends the app.
@@ -169,15 +183,22 @@ let refreshRate = 60
 
 /**
  * Calls `fn` before every frame is painted: `tick` is the time in ms, `frame` is
- * the present count, and `rate` is the current refresh rate in Hz. `tick` is paced
- * by the runtime (one refresh period per present, slow-corrected toward the wall
- * clock) so animations driven off it stay smooth even when swap-return times
- * jitter, and it is continuous across hot reloads: every tick an instance
- * sees is on one timebase, so dt is well-defined from the second call on.
- * Timers freeze together with frame callbacks under the dev tools' clock
- * control, but measure their delays against the wall clock, not this paced
- * timeline. performance.now() is not on it either: it is real elapsed time
- * for measuring work; Date.now() is calendar time.
+ * the present count, and `rate` is the current refresh rate in Hz. `tick`
+ * advances by the display refreshes since the previous frame, as the runtime
+ * counts them: exactly one refresh period per frame while the app keeps the
+ * refresh rate, and whole multiples of it when a frame takes longer (the
+ * requestAnimationFrame contract; a 21 fps app on a 90 Hz display sees
+ * 44 and 56 ms deltas, because that is how long each frame was on screen).
+ * Deltas are therefore honest and never lag the wall clock; an app that
+ * wants motion smoother than its own frame rate steps its simulation at a
+ * fixed rate or averages the deltas itself. A gap over half a second (the
+ * app was backgrounded) advances one period, not the gap. The timebase is
+ * continuous across hot reloads: every tick an instance sees is on one
+ * timebase, so dt is well-defined from the second call on. Timers freeze
+ * together with frame callbacks under the dev tools' clock control, but
+ * measure their delays against the wall clock, not this frame timeline.
+ * performance.now() is not on it either: it is real elapsed time for
+ * measuring work; Date.now() is calendar time.
  * Returns a cleanup function; also auto-cleans within an owned scope. Outside
  * one - an effect's apply phase, an event handler - the returned cleanup is
  * the only handle, so return it from the apply (`return onFrame(...)`) to run
@@ -410,6 +431,23 @@ export function onWindowFocus(fn: () => void) {
   return unsubscribe
 }
 
+/**
+ * Calls `fn` with a link handed to the running app from outside: a custom
+ * scheme link the OS routed here (another app, a QR code, a notification),
+ * or one a dev tool sent (`open_link` over MCP, `POST /__control__/link`).
+ * The raw string, exactly as it arrived; the app decides what it means, and
+ * it is untrusted input: validate before acting on any part of it. The link
+ * the app was *started* with is not an event (nothing was listening yet) but
+ * a fact: `env.launchLink`.
+ *
+ * Returns a cleanup function; also auto-cleans within an owned scope.
+ */
+export function onLink(fn: (link: string) => void) {
+  let unsubscribe = on("link", (e: { link: string }) => fn(e.link))
+  if (getOwner()) onCleanup(unsubscribe)
+  return unsubscribe
+}
+
 export function onWindowBlur(fn: () => void) {
   let unsubscribe = on("windowBlur", fn)
   if (getOwner()) onCleanup(unsubscribe)