@wardic/solid 0.0.0-stage → 1.0.0-rc.1

package/src/unstable/v2/provider.tsx

@@ -0,0 +1,524 @@
+/**
+ * `WardicProvider` for Solid 2 (`@wardic/solid/unstable/v2`, #209): one Effect runtime for a
+ * subtree, as the Solid 1 binding's provider (`../../provider.tsx`), over the same runtime and
+ * services (`../../runtime.ts`). What Solid 2 changes:
+ *
+ * - **No `batch`.** Solid 2 batches every update on a microtask, and a read lags its setter until
+ *   then. The flush gate needs a frame's Starting-style switches to have reached the elements
+ *   before it commits (ADR-0034), so it gets `flush(apply)`: the switches set their signals in a
+ *   synchronous flush scope, drained as it returns, with no microtask scheduled for them (#257
+ *   item 12). The gate runs them from its frame flush, outside any owner, where Solid 2 lets a
+ *   signal be written.
+ * - **A context value is its own provider** (`<WardicContext value={…}>`).
+ * - **`onSettled`** opens the Hydration hold where Solid 1 had `onMount` (`onSettledClientOnly`: a
+ *   server starts nothing, so it takes no hydration id).
+ * - **Appear animations' `<style>` goes through the head registry** (`useHead`, #209 PR 4a) where
+ *   Solid 1 had `useAssets`. Registered on the server only, in its function form, which the server
+ *   reads when it writes the head, once the shell has rendered: every element is entered then, with
+ *   its timing. A client never registers it, and leaves the server's in the head. A late chunk's
+ *   elements register their own, which streams with the chunk as a head patch (`ward.tsx`).
+ *
+ * @module
+ */
+import * as Bool from "effect/Boolean"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import { constUndefined, identity } from "effect/Function"
+import * as Latch from "effect/Latch"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type * as DefaultTransition from "@wardic/core/DefaultTransition"
+import type * as ReducedMotion from "@wardic/core/ReducedMotion"
+import type * as Renderer from "@wardic/core/Renderer"
+import type * as FlushGate from "@wardic/dom/FlushGate"
+import type * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+import { type HeadTag, isServer, type JSX, useHead } from "@solidjs/web"
+import { createContext, DEV, flush, isHydrating, onCleanup, onSettled, runWithOwner, untrack, useContext } from "solid-js"
+import * as Context from "effect/Context"
+import * as Report from "@wardic/dom/Report"
+import { type Feature, type FeatureRegistry, type FeatureSection, type FeaturesProp, ROOT, strictMessage } from "../../feature.ts"
+import { FeatureSectionContext, sectionUnder, useLazySection } from "./feature-section.ts"
+import { explainerOf, type ServerAppear, serverAppear } from "../../appear.ts"
+import {
+  animateLayoutOf,
+  clientContext,
+  fromContext,
+  interrupted,
+  prepareIdle,
+  reducedMotionSettingWith,
+  reducedMotionWith,
+  reported,
+  serverContext,
+  type WardicContextValue,
+  type WardicEnv,
+  type WardicRuntime,
+  type WardicServices,
+  whenIdle,
+} from "../../runtime.ts"
+import { onSettledClientOnly } from "./solid-reactivity.ts"
+import { useWardicConfig } from "./wardic-config.tsx"
+import { skipAnimationsOf } from "../../wardic-config-value.ts"
+import { instantLayoutOf, type InstantTransition, instantTransitionOf, resetOf } from "../../instant.ts"
+import type { WardicScaleCorrector } from "../../config.ts"
+
+/** A frame's Starting-style switches, applied and drained before the gate commits (ADR-0034): Solid 2's `batch`. */
+const applyAndFlush = (apply: () => void): void => {
+  flush(apply)
+}
+
+/**
+ * The runtime and services a provider carries down its subtree; `null` outside one. Solid 2 takes
+ * an `undefined` default for none, and its `useContext` then throws its own error outside a
+ * provider: `null` keeps Wardic's, which names the hook.
+ */
+const WardicContext = createContext<WardicContextValue | null>(null)
+
+/** The nearest provider's value, `undefined` outside one. */
+const contextValue = (): WardicContextValue | undefined => Option.getOrUndefined(Option.fromNullishOr(useContext(WardicContext)))
+
+/**
+ * Puts Wardic in your app: every Wardic element sits under one. Give it the Environment, `DomLive` in
+ * a browser, and the Features your elements use.
+ *
+ * @example
+ * <WardicProvider env={DomLive} features={[domAnimation]}>
+ *   <App />
+ * </WardicProvider>
+ * @see https://wardic.dev/reference/solid/provider/wardic-provider
+ */
+// As the Solid 1 binding's: one runtime made once from `env` (#51: built on first need), disposed on
+// unmount, inert during a server render (ADR-0021). reducedMotion is read as each animation starts
+// (ADR-0029), a WardicConfig's over it (#434); appear (ADR-0044, #585) on the server once.
+export function WardicProvider(props: {
+  /** The Environment Wardic runs in: `DomLive` in a browser, from `@wardic/dom`. Read once. */
+  readonly env: WardicEnv
+  /**
+   * How animations honour the visitor's reduced-motion setting: `"user"` follows it (the default),
+   * `"always"` reduces motion, `"never"` doesn't. Under it, what moves or resizes jumps to where it's
+   * going, and the rest, such as opacity, still animates. A `WardicConfig` sets it for a subtree.
+   */
+  readonly reducedMotion?: ReducedMotion.Config | undefined
+  /**
+   * On a server-rendered page, entrances play from the first paint, before the JavaScript has loaded
+   * (the default, `true`). `false` makes them wait for the JavaScript; `"explain"` plays them, and
+   * logs on the server why each element that can't play waits.
+   */
+  readonly appear?: boolean | "explain" | undefined
+  /**
+   * The nonce your page's Content Security Policy gives inline styles: the `<style>` a server render
+   * writes for its entrances carries it, a streamed chunk's too. Motion's `MotionConfig` `nonce`.
+   */
+  readonly nonce?: string | undefined
+  /**
+   * Your own corrections of a value a layout animation's scale would distort, by the key each corrects:
+   * Motion's `addScaleCorrector`, given here. Read once.
+   */
+  readonly scaleCorrectors?: Readonly<Record<string, WardicScaleCorrector>> | undefined
+  /**
+   * The Features every `w.*` element under it has: at once (`[domAnimation]`), or loaded with a
+   * function (`() => import("./features").then((m) => m.drag)`). Read once.
+   */
+  readonly features?: FeaturesProp | undefined
+  /** In development, a `wardic.*` element under it throws, so every element ships only its Features. */
+  readonly strict?: boolean | undefined
+  readonly children?: JSX.Element
+}): JSX.Element {
+  const value = Bool.match(isServer, {
+    onTrue: () => serverContext(props.env, serverAppearOf(props.appear, props.reducedMotion, props.nonce), () => untrack(() => props.reducedMotion)),
+    onFalse: () =>
+      clientContext(
+        props.env,
+        applyAndFlush,
+        () => untrack(() => props.reducedMotion),
+        // eslint-disable-next-line solid/reactivity -- the provider's setting, tracked too: `createReducedMotionConfig` reads it where it tracks (#584)
+        () => props.reducedMotion,
+        untrack(() => props.scaleCorrectors),
+      ),
+  })
+  // Disposing the runtime closes its Scope: the projection system, then the gate (#132). Its
+  // disposal rejects first, ending every `animateLayout` still waiting: their flights won't end (#257).
+  let abort = constUndefined as (reason: DOMException) => void
+  const disposed = new Promise<never>((_, reject) => {
+    abort = reject
+  })
+  // Each waiting call races it and handles it; with none, it's handled here.
+  disposed.catch(constUndefined)
+  disposals.set(value, disposed)
+  onCleanup(() => {
+    abort(new DOMException("The WardicProvider was disposed before its layout animations ended.", "AbortError"))
+    // Its Features end first, then the runtime they stand on (#511).
+    void value.features.dispose()
+  })
+  const section = sectionOf(value, ROOT, props)
+  sections.set(value, section)
+  // Built at the browser's idle time, after this render (#535): what a first element would build, so an
+  // element mounted after pays none of it. One mounted before then builds it itself, as before. Asked
+  // for here, with no computation of the provider's own (an `onSettled`'s would shift a hydration's
+  // owners from the server's), and on the client alone.
+  if (Bool.not(isServer)) onCleanup(whenIdle(() => prepareIdle(value, section)))
+  return <WardicContext value={value}>{props.children}</WardicContext>
+}
+
+/**
+ * Each provider's own section (#511): its Features, the first section of its tree. Kept beside its
+ * context value, not in a context of its own, so a provider renders one context, as before.
+ */
+// Module state (#460, Q7): each provider's root section, held weakly by its context value.
+const sections = new WeakMap<WardicContextValue, FeatureSection>()
+
+/**
+ * The section an element is in (#511): the nearest `LazyWardic`'s, else its provider's own; outside a
+ * provider, none. Internal.
+ */
+export function useFeatureSection(): FeatureSection {
+  return UndefinedOr.match(useLazySection(), {
+    onDefined: identity,
+    onUndefined: () => UndefinedOr.match(contextValue(), { onUndefined: () => ROOT, onDefined: (value) => UndefinedOr.getOrThrow(sections.get(value)) }),
+  })
+}
+
+/**
+ * The section `props` make under `parent` (#511), on `value`'s registry: a failed lazy load reported
+ * as a fiber's failure is (ADR-0030, decision 4).
+ */
+const sectionOf = (
+  value: WardicContextValue,
+  parent: FeatureSection,
+  props: { readonly features?: FeaturesProp | undefined; readonly strict?: boolean | undefined },
+): FeatureSection =>
+  sectionUnder(parent, value.features, untrack(() => props.features), untrack(() => props.strict) === true, (cause) => {
+    value.runtime.runFork(Report.failure("wardic.features: a lazy load of Features failed", cause))
+  })
+
+/**
+ * Gives the `w.*` elements in its section more Features, beside their provider's: at once
+ * (`features={[drag]}`), or loaded with a function, which runs as the section renders, so a page loads
+ * a Feature only when it needs it. Motion's `LazyMotion`.
+ *
+ * @example
+ * <LazyWardic features={() => import("./drag-feature").then((m) => m.drag)}>
+ *   <w.div drag />
+ * </LazyWardic>
+ * @see https://wardic.dev/reference/solid/provider/lazy-wardic
+ */
+// #511, ADR-0067, as the Solid 1 binding's: given at once, built at first need; loaded lazily, each
+// Feature takes effect as it arrives (#551, #582). A failed load is reported once; a server loads nothing.
+export function LazyWardic(props: {
+  /** Its Features: one, a list, or a function that loads them. Read once. */
+  readonly features: FeaturesProp
+  /** In development, a `wardic.*` element under it throws. Read once. */
+  readonly strict?: boolean | undefined
+  readonly children?: JSX.Element
+}): JSX.Element {
+  const section = fromContext(contextValue(), "LazyWardic", (value) => sectionOf(value, useFeatureSection(), props))
+  return <FeatureSectionContext value={section}>{props.children}</FeatureSectionContext>
+}
+
+/**
+ * The Features an element has (#511): its section's, and those it brings, a Complete element's every
+ * one (`brings`), built at once. A Complete element under a `strict` section is an error in
+ * development. Internal.
+ */
+export function useElementFeatures(brings: ReadonlyArray<Feature> | undefined, complete: boolean): FeatureSection {
+  const section = useFeatureSection()
+  if (DEV && complete && section.strict) throw new Error(strictMessage("wardic.*, wardic.create, ward()", "w.*, w.create, w.ward()"))
+  if (Predicate.isUndefined(brings)) return section
+  const registry = useFeatureRegistry()
+  // A Complete element has every Feature, whatever its section has: one section per provider.
+  if (complete) return registry.section(brings)
+  const own = registry.build(brings)
+  return { services: () => Context.merge(section.services(), own), pending: section.pending, strict: section.strict }
+}
+
+/** The provider's Features (#511). Internal. */
+export function useFeatureRegistry(): FeatureRegistry {
+  return fromContext(contextValue(), "useFeatureRegistry", (value) => value.features)
+}
+
+/**
+ * The services of `features`, which a hook or component brings (#511, decision 12) whatever its
+ * section has: built the first time they're read, on the client. `features` is a list the caller keeps,
+ * so its provider joins it once. Internal.
+ */
+export function useBrought(features: ReadonlyArray<Feature>): () => Context.Context<never> {
+  const registry = useFeatureRegistry()
+  return () => registry.build(features)
+}
+
+/** Each client provider's disposal (#257): a promise that rejects with an `AbortError` then. */
+// Module state (#460, Q7): each provider's disposal, held weakly by its context value.
+const disposals = new WeakMap<WardicContextValue, Promise<never>>()
+
+/**
+ * A server render's Appear animations (#48, ADR-0044), with the head's `<style>` registered for
+ * them, or `undefined` with `appear={false}`. Each element takes a slot as it renders; the head
+ * gets every rule and timing once the shell has rendered.
+ */
+const serverAppearOf = (appear: boolean | "explain" | undefined, reducedMotion: ReducedMotion.Config | undefined, nonce: string | undefined): ServerAppear | undefined => {
+  if (appear === false) return undefined
+  const state = serverAppear(UndefinedOr.match(reducedMotion, { onUndefined: () => "user" as const, onDefined: identity }), explainerOf(appear), nonce)
+  useHead(appearStyle(() => state.css(), nonce))
+  return state
+}
+
+/**
+ * The head tags for an Appear `<style>` whose CSS `css` gives, in `useHead`'s function form: read
+ * when the server writes the head, and once, so a second read can't find it written already. No
+ * tag when there's none to write. With a `nonce` (#618, P1), the tag carries it. Internal: the
+ * provider's, and a late chunk's (`ward.tsx`).
+ */
+export const appearStyle = (css: () => string, nonce: string | undefined): (() => Array<HeadTag>) => {
+  let tags: Array<HeadTag> | undefined
+  return () => {
+    if (Predicate.isUndefined(tags)) tags = styleTags(css(), nonce)
+    return tags
+  }
+}
+
+const styleTags = (css: string, nonce: string | undefined): Array<HeadTag> => {
+  if (css === "") return []
+  if (Predicate.isUndefined(nonce)) return [{ tag: "style", props: { "data-wardic-appear": "", children: css } }]
+  return [{ tag: "style", props: { "data-wardic-appear": "", nonce, children: css } }]
+}
+
+/** A server render's Appear animations; `undefined` on the client, or with `appear={false}`. Internal. */
+export function useWardicAppear(): ServerAppear | undefined {
+  return UndefinedOr.match(contextValue(), { onUndefined: constUndefined, onDefined: (value) => value.appear })
+}
+
+/**
+ * The nearest `WardicProvider`'s Effect runtime, for running Effect code on Wardic's services: its
+ * clock, frame loop, renderer, probe and the rest. Throws outside a provider. During a server render
+ * it isn't built: hold it, but run on it only once the element has mounted.
+ *
+ * @example
+ * const runtime = useWardicRuntime()
+ * onSettled(() => {
+ *   runtime.runFork(Effect.log("mounted"))
+ * })
+ * @see https://wardic.dev/reference/solid/advanced/runtime
+ */
+// ADR-0021: a server builds no runtime, and DomLive refuses with its client-only error.
+export function useWardicRuntime(): WardicRuntime {
+  return fromContext(contextValue(), "useWardicRuntime", (value) => value.runtime)
+}
+
+/**
+ * The nearest `WardicProvider`'s flush gate: what a binding registers its elements with, and writes
+ * their values into, committed once a frame. For building an element of your own on Wardic's
+ * rendering. Throws outside a provider; during a server render it's an inert gate that does nothing.
+ *
+ * @see https://wardic.dev/reference/solid/advanced/flush-gate
+ */
+// ADR-0006; inert on a server (ADR-0021, decision 9).
+export function useWardicGate(): FlushGate.Shape {
+  return fromContext(contextValue(), "useWardicGate", (value) => value.gate)
+}
+
+/** The Environment's Renderer (ADR-0003), read once by the provider: what an element and a presence project and commit through. Internal. */
+export function useWardicRenderer(): Renderer.Renderer["Service"] {
+  return fromContext(contextValue(), "useWardicRenderer", (value) => value.renderer)
+}
+
+/** The Environment's Positional keys (ADR-0036): which keys reduced motion Snaps. Internal. */
+export function useWardicPositionalKeys(): ReducedMotion.PositionalKeys["Service"] {
+  return fromContext(contextValue(), "useWardicPositionalKeys", (value) => value.positionalKeys)
+}
+
+/** The Environment's Default transition (ADR-0051): what a key with no transition of its own runs on. Internal. */
+export function useWardicDefaultTransition(): DefaultTransition.DefaultTransition["Service"] {
+  return fromContext(contextValue(), "useWardicDefaultTransition", (value) => value.defaultTransition)
+}
+
+/**
+ * Whether reduced motion applies now (ADR-0029): the nearest `WardicConfig`'s `reducedMotion` (#434),
+ * else the provider's, and the user's preference; always `false` during a server render. Internal.
+ */
+export function useWardicReducedMotion(): () => boolean {
+  const config = useWardicConfig()
+  return fromContext(contextValue(), "useWardicReducedMotion", (value) => reducedMotionWith(value, config))
+}
+
+/**
+ * Whether the elements here skip their animations now (#468): the nearest `WardicConfig`'s
+ * `skipAnimations`, or the provider's Instant change while one runs (#443). Read when each starts.
+ * Internal.
+ */
+export function useWardicSkipAnimations(): () => boolean {
+  const config = skipAnimationsOf(useWardicConfig())
+  const value = contextValue()
+  if (Predicate.isUndefined(value)) return config
+  const instant = value.instant
+  return () => Bool.or(instant.active(), config())
+}
+
+/**
+ * Makes a layout change land at once: `start(fn)` runs `fn`, and every layout element goes straight
+ * to its new box, a running layout animation ending there too. The change's other animations run as
+ * ever. `start()` with no function does the same for a change made later in the task. Motion's
+ * `useInstantLayoutTransition`. On a server it runs `fn`.
+ *
+ * @example
+ * const start = createInstantLayoutTransition()
+ * start(() => setOrder(sorted()))
+ * @see https://wardic.dev/reference/solid/layout/create-instant-layout-transition
+ */
+// #443, as Solid 1's: an Instant change of the layout, the projection system's `instant`.
+export function createInstantLayoutTransition(): (fn?: () => void) => void {
+  return fromContext(contextValue(), "createInstantLayoutTransition", (value) => instantLayoutOf(() => value.projection))
+}
+
+/**
+ * Makes a change land at once, with no animation: `start(fn)` runs `fn`, and its layout change and
+ * every animation that starts until two frames after the call land where they're going. A later call
+ * extends it, and `start.end()` ends it now. For a change that shouldn't animate: a reset, a jump to
+ * a route. Motion's `useInstantTransition`.
+ *
+ * @example
+ * const start = createInstantTransition()
+ * <button onClick={() => start(() => setOpen(all))}>Open all</button>
+ * @see https://wardic.dev/reference/solid/layout/create-instant-transition
+ */
+// #443, as Solid 1's: an Instant change, each animation it covers a Skipped animation (#468).
+export function createInstantTransition(): InstantTransition {
+  return fromContext(contextValue(), "createInstantTransition", (value) => instantTransitionOf(() => value.projection, () => value.instant))
+}
+
+/**
+ * Starts layout animations afresh: `reset()` ends every running layout animation where the layout puts
+ * its element, lets go of every leaving `layoutId` element, and has the next measure take every box as
+ * it is, animating none. For a change that replaces the page wholesale. Motion's `useResetProjection`.
+ * On a server it does nothing.
+ *
+ * @example
+ * const reset = createResetProjection()
+ * const openWorkspace = (id: string) => {
+ *   reset()
+ *   setWorkspace(id)
+ * }
+ * @see https://wardic.dev/reference/solid/layout/create-reset-projection
+ */
+// #443, as Solid 1's: a Projection reset, the projection system's `reset`: leavers and Switch seeds dropped.
+export function createResetProjection(): () => void {
+  return fromContext(contextValue(), "createResetProjection", (value) => resetOf(() => value.projection))
+}
+
+/**
+ * The reduced-motion setting that applies here (#443): the nearest `WardicConfig`'s `reducedMotion`,
+ * else the provider's, else `"user"`, each tracked (#584). Internal.
+ */
+export function useWardicReducedMotionSetting(): () => ReducedMotion.Config {
+  const config = useWardicConfig()
+  return fromContext(contextValue(), "useWardicReducedMotionSetting", (value) => reducedMotionSettingWith(value, config))
+}
+
+/**
+ * `read` of the nearest provider's context value, named `name` in the error outside one: for a hook in
+ * a module of its own (#548), such as `useWardicProjection`, which brings `layout`.
+ */
+export const fromWardicContext = <A,>(name: string, read: (value: WardicContextValue) => A): A => fromContext(contextValue(), name, read)
+
+/**
+ * The provider's projection system once its `layout` Feature is built (#511), read as it's needed;
+ * `undefined` until then, and during a server render. For what brings no `layout` and works with the
+ * layout elements that are there: an element registering its values, a presence. Internal.
+ */
+export function useBuiltProjection(): () => ProjectionSystem.Shape | undefined {
+  return fromContext(contextValue(), "useBuiltProjection", (value) => () => value.projection)
+}
+
+/**
+ * `useAnimateLayout()`'s function: `animateLayout(fn)` runs `fn` at once, a throw from it thrown here,
+ * and animates the layout change it makes. Its promise resolves with what `fn` returns once every
+ * layout animation the change started has ended, however each ended; calls in one task resolve
+ * together. It rejects with an `AbortError` if the provider goes first. On a server, `fn` just runs.
+ */
+// #4, ADR-0038; #257, ADR-0046: a Declared layout change, its promise replacing ADR-0039's `onSettled`.
+export type AnimateLayout = <A>(fn: () => A) => Promise<Awaited<A>>
+
+/**
+ * Animates a layout change you make: `animateLayout(fn)` runs `fn`, and every layout element animates
+ * from where it was at the call to where the change puts it. For a change nothing else sees, such as a
+ * keyed `<For>` reordered or a plain element's class changed. A write Solid holds, inside an `action`
+ * or beside a write that starts async work, animates once it lands. Its promise resolves with what
+ * `fn` returns once the animations it started have ended. Only what `fn` changes synchronously
+ * animates. Throws outside a `WardicProvider`.
+ *
+ * @example
+ * const animateLayout = useAnimateLayout()
+ * const shuffle = () => animateLayout(() => setItems(shuffled(items())))
+ * @see https://wardic.dev/reference/solid/layout/use-animate-layout
+ */
+export function useAnimateLayout(): AnimateLayout {
+  const value = contextValue()
+  const declare = animateLayoutOf(value)
+  const disposed = UndefinedOr.match(value, { onUndefined: constUndefined, onDefined: (v) => disposals.get(v) })
+  return <A,>(fn: () => A): Promise<Awaited<A>> => {
+    // A server render has nothing to animate, and never settles.
+    if (isServer) return Promise.resolve(declare(fn)) as Promise<Awaited<A>>
+    let settle = constUndefined as () => void
+    const settled = new Promise<void>((resolve) => {
+      settle = resolve
+    })
+    // A throw from `fn` is thrown here: `settled` is just dropped, unsettled.
+    const result = declare(fn)
+    // Once what the call is part of has settled, a pass from the boxes the last one kept: it folds into
+    // the call's own when nothing was held, and measures a write Solid 2 held (inside an action, or in
+    // the frame of a write that started async work) once it lands. The promise waits for that pass's
+    // animations (#618, decision 13). Unowned, so it runs once whatever the caller's owner does: an
+    // owner disposed first would drop it, and the promise with it.
+    runWithOwner(null, () =>
+      onSettled(() => {
+        declare(constUndefined, { from: "lastPass", onSettled: () => settle() })
+      }),
+    )
+    const waiting = UndefinedOr.match(disposed, { onUndefined: () => settled, onDefined: (gone) => Promise.race([settled, gone]) })
+    return waiting.then(() => result) as Promise<Awaited<A>>
+  }
+}
+
+/**
+ * Runs `effect` on `runtime`, and interrupts it as the current owner is cleaned up, its Scope closed
+ * with it. Returns its fiber. A failure is logged and reported to the Environment's error reporters;
+ * an interruption is neither. On a server it starts nothing, and while hydrating it starts once its owner has settled.
+ * Call it within a Solid owner.
+ *
+ * @example
+ * runScoped(runtime, Stream.runForEach(ticks, (t) => Effect.sync(() => setTick(t))))
+ * @see https://wardic.dev/reference/solid/advanced/runtime
+ */
+// ADR-0006: the per-element fiber lifecycle; a failure is `wardic.runScoped: a fiber failed`
+// (ADR-0030, decision 4); the Hydration hold (ADR-0021 decisions 8 and 9).
+export function runScoped<A, E>(runtime: WardicRuntime, effect: Effect.Effect<A, E, WardicServices>): Fiber.Fiber<A, E> {
+  if (isServer) return interrupted<A, E>()
+  const run = reported(effect)
+  if (isHydrating()) {
+    const latch = Latch.makeUnsafe(false)
+    const held = runtime.runFork(Effect.andThen(latch.await, run))
+    onSettledClientOnly(() => {
+      latch.openUnsafe()
+    })
+    onCleanup(() => held.interruptUnsafe())
+    return held
+  }
+  const fiber = runtime.runFork(run)
+  // Interrupted where the cleanup runs, nothing waiting on its end, as `runCallback`'s interruptor
+  // does: a forked `Fiber.interrupt` was a fiber of its own for each (#618, L2).
+  onCleanup(() => fiber.interruptUnsafe())
+  return fiber
+}
+
+/**
+ * Runs the Effect `effectThunk` makes on the provider's runtime, as `runScoped` does, until the
+ * current owner is cleaned up. The thunk is called once; not on a server. Returns its fiber.
+ *
+ * @example
+ * useWardicFiber(() => Stream.runForEach(ticks, (t) => Effect.sync(() => setTick(t))))
+ * @see https://wardic.dev/reference/solid/advanced/runtime
+ */
+export function useWardicFiber<A, E>(effectThunk: () => Effect.Effect<A, E, WardicServices>): Fiber.Fiber<A, E> {
+  const runtime = useWardicRuntime()
+  if (isServer) return interrupted<A, E>()
+  return runScoped(runtime, effectThunk())
+}