@pyreon/zero 0.14.0 → 0.16.0

package/src/og-image.ts

@@ -153,21 +153,21 @@ export function buildTextOverlaySvg(
     let currentLine = ''
 
     const estimateWidth = (s: string): number => {
-      let width = 0
+      let w = 0
       for (let i = 0; i < s.length; i++) {
         const code = s.charCodeAt(i)
         if (code >= 0x3000 && code <= 0x9FFF) {
           // CJK characters — full width
-          width += fontSize * 1.0
+          w += fontSize * 1.0
         } else if (code <= 0x7E && 'iljft!|:;.,\''.includes(s[i]!)) {
           // Narrow Latin characters
-          width += fontSize * 0.35
+          w += fontSize * 0.35
         } else {
           // Regular Latin characters
-          width += fontSize * 0.55
+          w += fontSize * 0.55
         }
       }
-      return width
+      return w
     }
 
     for (const word of words) {

package/src/script.tsx

@@ -1,5 +1,6 @@
-import type { VNodeChild } from '@pyreon/core'
+import type { Ref, VNodeChild } from '@pyreon/core'
 import { createRef, onMount, onUnmount } from '@pyreon/core'
+import { signal } from '@pyreon/reactivity'
 import { useIntersectionObserver } from './utils/use-intersection-observer'
 
 // ─── Script optimization component ─────────────────────────────────────────
@@ -9,7 +10,12 @@ import { useIntersectionObserver } from './utils/use-intersection-observer'
 // - Load on idle (requestIdleCallback)
 // - Load on interaction (click, scroll, etc.)
 // - Load on viewport entry
-// - Worker offloading for analytics scripts
+//
+// Three levels of API (mirrors @pyreon/zero/link and @pyreon/zero/image):
+//
+// 1. useScript(props)   — composable returning load-state signals + sentinel ref
+// 2. createScript(Comp) — HOC wrapping any component with script load behavior
+// 3. Script             — default sentinel-or-null component (built on createScript)
 
 export interface ScriptProps {
   /** Script source URL. */
@@ -22,9 +28,9 @@ export interface ScriptProps {
   id?: string
   /** Async attribute. Default: true */
   async?: boolean
-  /** onLoad callback. */
+  /** onLoad callback — fires when the `<script>` finishes loading. */
   onLoad?: () => void
-  /** onError callback. */
+  /** onError callback — fires when the `<script>` fails to load. */
   onError?: (error: Error) => void
 }
 
@@ -35,57 +41,115 @@ export type ScriptStrategy =
   | 'onInteraction'
   | 'onViewport'
 
+/** Return type of {@link useScript}. */
+export interface UseScriptReturn {
+  /** Ref — attach to the sentinel element for `onViewport` strategy. Undefined for other strategies. */
+  sentinelRef: Ref<HTMLElement> | undefined
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean
+  /** Whether the script is in the strategy state machine awaiting a trigger (idle/interaction/viewport). */
+  pending: () => boolean
+  /** Whether the consumer needs to render a sentinel element (only true for `onViewport`). */
+  needsSentinel: boolean
+  /** Imperatively trigger the script load. Already invoked automatically by the strategy. */
+  load: () => void
+}
+
+/** Props passed to a custom component via {@link createScript}. */
+export interface ScriptRenderProps {
+  /** Ref — attach to whatever sentinel element you render (only matters for `onViewport`). */
+  sentinelRef: Ref<HTMLElement> | undefined
+  /** Whether the script is in viewport-wait mode (true → render a sentinel; false → render null). */
+  needsSentinel: boolean
+  /** Whether the script has finished loading (onLoad fired). */
+  loaded: () => boolean
+  /** Whether the script load failed (onError fired). */
+  errored: () => boolean
+  /** Whether the script is in the strategy state machine awaiting a trigger. */
+  pending: () => boolean
+}
+
 /**
- * Optimized script loading component.
+ * Composable that provides all script loading behavior — strategy state
+ * machine (afterHydration / onIdle / onInteraction / onViewport),
+ * deduplication, load/error tracking.
  *
- * @example
- * // Load analytics after page is interactive
- * <Script src="https://analytics.example.com/script.js" strategy="onIdle" />
- *
- * // Load chat widget when user scrolls
- * <Script src="/chat-widget.js" strategy="onViewport" />
+ * Returns reactive signals (`loaded`, `errored`, `pending`) so consumers
+ * can render loading indicators, retry buttons, or analytics-readiness
+ * gates without re-implementing the strategy machine.
  *
- * // Inline script with deferred execution
- * <Script strategy="afterHydration">
- *   {`console.log("App hydrated!")`}
- * </Script>
+ * @example
+ * function MyScript(props: ScriptProps) {
+ *   const s = useScript(props)
+ *   return (
+ *     <>
+ *       {() => s.loaded() ? <Analytics /> : <Skeleton />}
+ *       {() => s.needsSentinel && <div ref={s.sentinelRef} style="width:0;height:0" />}
+ *     </>
+ *   )
+ * }
  */
-export function Script(props: ScriptProps): VNodeChild {
+export function useScript(props: ScriptProps): UseScriptReturn {
+  const strategy = props.strategy ?? 'afterHydration'
+  const loaded = signal(false)
+  const errored = signal(false)
+  const pending = signal(strategy !== 'beforeHydration' && strategy !== 'afterHydration')
+  const sentinelRef = strategy === 'onViewport' ? createRef<HTMLElement>() : undefined
+
   function loadScript() {
-    // Only invoked from `onMount` — explicit guard documents the
-    // SSR-safety contract at the callsite (the rule can't AST-trace the
-    // indirect call).
+    // Only invoked from `onMount` or strategy triggers — explicit guard
+    // documents the SSR-safety contract at the callsite (the rule can't
+    // AST-trace the indirect call).
     if (typeof document === 'undefined') return
-    // Deduplication
-    if (props.id && document.getElementById(props.id)) return
+    // Deduplication — short-circuit if a script with the same id exists.
+    if (props.id && document.getElementById(props.id)) {
+      loaded.set(true)
+      pending.set(false)
+      return
+    }
 
     const script = document.createElement('script')
     if (props.src) script.src = props.src
     if (props.id) script.id = props.id
     script.async = props.async !== false
 
-    if (props.onLoad) script.onload = props.onLoad
-    if (props.onError) {
-      script.onerror = () => props.onError?.(new Error(`Failed to load: ${props.src}`))
+    script.onload = () => {
+      loaded.set(true)
+      pending.set(false)
+      props.onLoad?.()
+    }
+    script.onerror = () => {
+      errored.set(true)
+      pending.set(false)
+      props.onError?.(new Error(`Failed to load: ${props.src}`))
     }
 
     if (props.children && !props.src) {
       script.textContent = props.children
+      // Inline scripts have no async load event — mark loaded synchronously
+      // post-append so consumers can react. setTimeout 0 keeps the order
+      // (DOM append → script body executes → next microtask → signals update).
+      setTimeout(() => {
+        loaded.set(true)
+        pending.set(false)
+      }, 0)
     }
 
     document.head.appendChild(script)
   }
 
   onMount(() => {
-    const strategy = props.strategy ?? 'afterHydration'
-
     switch (strategy) {
       case 'beforeHydration':
-        // Already in HTML — do nothing
+        // Already in HTML — do nothing.
+        loaded.set(true)
+        pending.set(false)
         break
 
       case 'afterHydration':
-        // Load immediately after mount (hydration is complete)
+        // Load immediately after mount (hydration is complete).
         loadScript()
         break
 
@@ -113,25 +177,84 @@ export function Script(props: ScriptProps): VNodeChild {
       }
 
       case 'onViewport':
-        // Handled below via useIntersectionObserver on the sentinel element
+        // Handled below via useIntersectionObserver on the sentinel ref.
         break
     }
     return undefined
   })
 
-  const sentinelRef = createRef<HTMLElement>()
-  const strategy = props.strategy ?? 'afterHydration'
-
   if (strategy === 'onViewport') {
     useIntersectionObserver(
-      () => sentinelRef.current ?? undefined,
+      () => sentinelRef!.current ?? undefined,
       () => loadScript(),
     )
   }
 
-  if (strategy === 'onViewport') {
-    return <div ref={sentinelRef} style="width:0;height:0;overflow:hidden" />
+  return {
+    sentinelRef,
+    loaded,
+    errored,
+    pending,
+    needsSentinel: strategy === 'onViewport',
+    load: loadScript,
   }
+}
 
-  return null
+/**
+ * Higher-order component that wraps any component with script load behavior.
+ *
+ * The wrapped component receives {@link ScriptRenderProps} with the sentinel
+ * ref, load-state signals, and a `needsSentinel` flag. Use this when you want
+ * to render a loading indicator, retry button, or custom analytics-readiness
+ * gate around the script load.
+ *
+ * @example
+ * // Script with a loading indicator
+ * const TrackedScript = createScript((props) => (
+ *   <>
+ *     {() => props.pending() && <Spinner />}
+ *     {() => props.errored() && <button onClick={() => location.reload()}>Retry</button>}
+ *     {props.needsSentinel && <div ref={props.sentinelRef} style="width:0;height:0" />}
+ *   </>
+ * ))
+ *
+ * <TrackedScript src="/analytics.js" strategy="onIdle" />
+ */
+export function createScript(
+  Component: (p: ScriptRenderProps) => any,
+): (props: ScriptProps) => any {
+  return function WrappedScript(props: ScriptProps) {
+    const s = useScript(props)
+    return (
+      <Component
+        sentinelRef={s.sentinelRef}
+        needsSentinel={s.needsSentinel}
+        loaded={s.loaded}
+        errored={s.errored}
+        pending={s.pending}
+      />
+    )
+  }
 }
+
+/**
+ * Default optimized script component. Renders a 0×0 sentinel `<div>` for the
+ * `onViewport` strategy (so IntersectionObserver has an element to observe),
+ * `null` for every other strategy.
+ *
+ * @example
+ * // Load analytics after page is interactive
+ * <Script src="https://analytics.example.com/script.js" strategy="onIdle" />
+ *
+ * // Load chat widget when user scrolls
+ * <Script src="/chat-widget.js" strategy="onViewport" />
+ *
+ * // Inline script with deferred execution
+ * <Script strategy="afterHydration">
+ *   {`console.log("App hydrated!")`}
+ * </Script>
+ */
+export const Script: (props: ScriptProps) => VNodeChild = createScript((props) => {
+  if (!props.needsSentinel) return null
+  return <div ref={props.sentinelRef} style="width:0;height:0;overflow:hidden" />
+})