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

package/src/drag-transition.ts

@@ -0,0 +1,43 @@
+/**
+ * An element's drag transition (ADR-0016, *Amendment (#140)*), Solid-free (#209): what every release
+ * runs on, a Fling, a snap back to the origin, and a layout node's Release offset, in both bindings.
+ *
+ * @module
+ */
+import type * as ProjectionSystem from "@wardic/dom/ProjectionSystem"
+import * as Bool from "effect/Boolean"
+import { identity } from "effect/Function"
+import * as UndefinedOr from "effect/UndefinedOr"
+import type { WardicDragTransition } from "./config.ts"
+
+/** Motion's `dragElastic` default (`defaultElastic`, ADR-0016 *Amendment (#140)*). */
+export const DEFAULT_DRAG_ELASTIC = 0.35
+
+/** A drag's `dragElastic`, or Motion's default. */
+export const elasticOf = (elastic: number | undefined): number =>
+  UndefinedOr.match(elastic, { onUndefined: () => DEFAULT_DRAG_ELASTIC, onDefined: identity })
+
+/** Motion's release (`startAnimation`), in seconds: a 0.75 s time constant, power 0.8, at rest within 1 px and 10 px/s. */
+const MOTION_RELEASE = { power: 0.8, timeConstant: 0.75, restDelta: 1, restSpeed: 10 } as const
+/** The bounce with an elastic drag, Motion's `dragElastic ? 200 : …`. */
+const ELASTIC_BOUNCE = { bounceStiffness: 200, bounceDamping: 40 } as const
+/** The bounce with none, a wall: Motion's `… : 1000000` and `10000000`. */
+const RIGID_BOUNCE = { bounceStiffness: 1e6, bounceDamping: 1e7 } as const
+
+/**
+ * An element's drag transition, resolved (ADR-0016, *Amendment (#140)*): Motion's release, its bounce
+ * from `dragElastic` (a wall with none), then the element's own `dragTransition` over it, its
+ * `timeConstant` from milliseconds to seconds. What every release runs on: a Fling, a snap back to the
+ * origin, and a projection node's Release offset.
+ */
+export const dragTransitionOf = (elastic: number | undefined, own: WardicDragTransition | undefined): ProjectionSystem.DragTransition => ({
+  ...MOTION_RELEASE,
+  ...Bool.match(elasticOf(elastic) !== 0, { onTrue: () => ELASTIC_BOUNCE, onFalse: () => RIGID_BOUNCE }),
+  ...UndefinedOr.match(own, {
+    onUndefined: () => ({}),
+    onDefined: ({ timeConstant, ...rest }) => ({
+      ...rest,
+      ...UndefinedOr.match(timeConstant, { onUndefined: () => ({}), onDefined: (ms) => ({ timeConstant: ms / 1000 }) }),
+    }),
+  }),
+})

package/src/drag.ts

@@ -0,0 +1,58 @@
+/**
+ * `runDragTrack` (ADR-0004): the Solid 1 binding's drag track, the shared one (`drag-track.ts`), its
+ * watches run by `runWatch` in a Scope the caller's owner closes, and its responses forked on the
+ * provider runtime (#379). The track is the `drag` Feature's (#511): `runDragTrack` brings it.
+ */
+import * as InputSource from "@wardic/core/InputSource"
+import * as Effect from "effect/Effect"
+import { DEFAULT_DRAG_ELASTIC, dragTransitionOf } from "./drag-transition.ts"
+import { driveDragTrack, type DragTrack, type DragTrackOptions } from "./drag-track.ts"
+import type { Feature } from "./feature.ts"
+import { drag } from "./features/drag.ts"
+import { inputIn } from "./gesture-features.ts"
+import { runWatch, useBrought } from "./provider.tsx"
+import type { WardicRuntime } from "./runtime.ts"
+import { type DragGesture } from "./features/keys.ts"
+
+export { DEFAULT_DRAG_ELASTIC, dragTransitionOf }
+export type { DragSnapshot, DragTrack, DragTrackConfig } from "./drag-track.ts"
+
+/** `runDragTrack`'s options: the element, its drag config, the spine's snapshot and callbacks, and the provider's runtime. */
+export interface RunDragTrackOptions extends Omit<DragTrackOptions, "watch" | "fork"> {
+  /** The provider runtime the track's watches and responses run on. */
+  readonly runtime: WardicRuntime
+}
+
+/**
+ * Runs a drag on `opts.element` as a Wardic element's own drag runs: its gesture, constraints, elastic,
+ * release and drag claims, writing `x` and `y` through the element's snapshot. For an element of your
+ * own built on Wardic's drag. Stopped as the current owner is cleaned up. Brings the `drag` Feature.
+ * Solid 1 only.
+ *
+ * @see https://wardic.dev/reference/solid/advanced/run-drag-track
+ */
+// `drag-track.ts`, ADR-0004: its watches in a Scope of their own via `runWatch`, no fiber at rest, closed
+// by the caller's owner, which stops the watches and an in-flight release (#379). Its hold on x/y goes
+// to the spine (#340).
+export const runDragTrack = (opts: RunDragTrackOptions): DragTrack => {
+  // The gestures' input, read as the track first watches, on the client: a server render runs no watch.
+  const services = useBrought(BRINGS)
+  const given = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, Exclude<R, InputSource.InputSource>> =>
+    Effect.provideService(effect, InputSource.InputSource, inputIn(services()))
+  return driveDragTrack({
+    ...opts,
+    watch: (track) => runWatch(opts.runtime, (onDefect) => given(track(onDefect))),
+    fork: (response) => void opts.runtime.runFork(given(response)),
+  })
+}
+
+/** What {@link runDragTrack} brings (ADR-0067 decision 12): the `drag` Feature, whatever its section has (#511). */
+const BRINGS: ReadonlyArray<Feature> = [drag]
+
+/** {@link runDragTrack} through `drive`: an element's section's `drag` Feature's (#511), where `runDragTrack` brings it. Internal. */
+export const runDragTrackWith = (drive: DragGesture["Service"]["drive"], opts: RunDragTrackOptions): DragTrack =>
+  drive({
+    ...opts,
+    watch: (track) => runWatch(opts.runtime, track),
+    fork: (response) => void opts.runtime.runFork(response),
+  })

package/src/element-style.ts

@@ -0,0 +1,112 @@
+/**
+ * The `style` a Wardic element is rendered with, for a `createWard` spread and a
+ * `wardic.create(Component)` wrap (ADR-0021 decision 6, ADR-0034). The flush gate commits every
+ * frame onto the element, so `style` carries Wardic's values only until the first commit:
+ *
+ * - until then, the user's style with the Starting style on top: what a server renders, what
+ *   hydration keeps, and what the element shows before its first frame;
+ * - from the first commit, the fallback: the user's style without the keys the gate holds on the
+ *   element. Wardic writes those while it drives them; a key the gate lets go of comes back.
+ *
+ * The gate switches it through the sink's hooks, outside its commits: `beforeFirstCommit`, and
+ * `onHeld` whenever the keys it holds change. Only a change to a key the element's own style
+ * sets re-runs `style`, so a frame never does. A ward's element that comes after the last one left
+ * the page enters fresh (#414): `restart` puts a Starting style back on until its first commit.
+ *
+ * The user's routed keys (#130, ADR-0043: its Live values and transform keys) are never Solid's:
+ * the Starting style carries their values, and from mount the gate holds them. Each style the
+ * user gives is seen by the element's {@link LiveStyle} here, where it's read reactively.
+ *
+ * Solid-free (#209): its state is plain, and one {@link Trigger} re-runs `style`, so it reads the
+ * same under Solid 2, where a signal's read lags its write until the flush.
+ */
+import type * as Renderer from "@wardic/core/Renderer"
+import type * as Values from "@wardic/core/Values"
+import type * as FlushGate from "@wardic/dom/FlushGate"
+import * as Style from "@wardic/dom/Style"
+import * as Bool from "effect/Boolean"
+import { constUndefined } from "effect/Function"
+import * as Rec from "effect/Record"
+import type { LiveStyle } from "./live-style.ts"
+import type { Reactivity } from "./reactivity.ts"
+
+/** What {@link createElementStyle} reads. */
+export interface ElementStyleOptions {
+  /** The user's current style, read when the keys the gate holds change. */
+  readonly userStyle: () => object | string | undefined
+  /** The element's Starting style, with no routed key. */
+  readonly starting: Renderer.Patch
+  /** The element's Starting style with its routed keys at `routed` (#130). */
+  readonly startingWith: (routed: Values.Values) => Renderer.Patch
+  /** The element's routed `style` keys (#130). */
+  readonly live: LiveStyle
+  /** A drag element's defaults, under the user's style. */
+  readonly defaults: Style.DragDefaults | undefined
+  /** A `<Reorder>` item's base style, under the user's style. */
+  readonly base?: (() => object | undefined) | undefined
+  /** The binding's Solid (#209). */
+  readonly reactivity: Reactivity
+}
+
+/** An element's `style` and the sink hooks that switch it. */
+export interface ElementStyle {
+  /** The element's style, given the user's: reactive, read inside the element's JSX. */
+  readonly style: (user: object | string | undefined) => Style.Style
+  /** The hooks the element's flush sink carries. */
+  readonly hooks: Required<Pick<FlushGate.Sink, "beforeFirstCommit" | "onHeld">>
+  /**
+   * Put `starting` on as the Starting style again, until the gate's next first commit: a new
+   * element entering fresh (#414), its sink registered after this call.
+   */
+  readonly restart: (starting: Renderer.Patch) => void
+}
+
+/** An element's `style`, switched by its flush sink's hooks. Call within a Solid owner. */
+export const createElementStyle = (options: ElementStyleOptions): ElementStyle => {
+  const { userStyle, startingWith, live, defaults, base = constUndefined, reactivity } = options
+  const { untrack } = reactivity
+  // The Starting style: the element's first, or a fresh entry's (#414).
+  let starting = options.starting
+  // Whether the gate has committed: `style` re-runs once, at the first commit.
+  let committed = false
+  // Every key the gate holds, current whenever `style` runs. A change that touches the
+  // element's own style re-runs it; any other change waits for the next run.
+  let held: ReadonlyArray<string> = []
+  const changed = reactivity.trigger()
+
+  // The Starting style with the routed keys' values now: read before the first commit only.
+  const startingNow = (): Renderer.Patch => {
+    const routed = live.values()
+    return Bool.match(Rec.isEmptyRecord(routed), { onTrue: () => starting, onFalse: () => startingWith(routed) })
+  }
+
+  const style = (user: object | string | undefined): Style.Style => {
+    changed.track()
+    const css = live.css(user)
+    return Bool.match(committed, {
+      onFalse: () => Style.over(Style.over(Style.over(startingNow(), css), base()), defaults),
+      onTrue: () => Style.without(Style.over(Style.over(css, base()), defaults), held),
+    })
+  }
+
+  const onHeld = (next: ReadonlyArray<string>): void => {
+    const prev = held
+    held = next
+    if (!committed) return
+    const style = Style.over(Style.over(live.css(untrack(userStyle)), untrack(base)), defaults)
+    if (Style.heldTouches(style, prev, next)) changed.notify()
+  }
+
+  const beforeFirstCommit = (): void => {
+    committed = true
+    changed.notify()
+  }
+
+  const restart = (next: Renderer.Patch): void => {
+    starting = next
+    committed = false
+    changed.notify()
+  }
+
+  return { style, hooks: { beforeFirstCommit, onHeld }, restart }
+}

package/src/element.tsx

@@ -0,0 +1,400 @@
+/**
+ * What every Wardic element's component form shares, for the Solid 1 binding (#511): `createWith`,
+ * which makes `wardic.create`'s component and `w.create`'s, a Complete element's or a Slim one's by the
+ * `kind` it's given, and the forms' proxy. `wardic.tsx` holds the Complete forms, `w.tsx` the Slim ones;
+ * this module names no Feature, so a Slim element's app ships none it doesn't choose (ADR-0067).
+ *
+ * `create(tag)` returns a Solid component that accepts the element's own props PLUS Wardic's motion
+ * props (`initial` / `animate` / `whileHover` / ...), wires them through {@link createWardWith}, and
+ * renders the underlying element with the user's props passed through. The flush gate commits each
+ * frame onto the element (ADR-0034). `create(Component)` is the same over the component, which
+ * forwards its `ref` to its root element (#253).
+ *
+ * Locked merge policy (Option A) — the merge now lives in `ward()`
+ * ({@link createWardWith}); this HOC just forwards the user's `ref` + `style` into it:
+ *   - Motion props are split off so none leak to the DOM (even ones not yet
+ *     wired by {@link createWardWith}).
+ *   - The user's `ref` AND Wardic's ref are both invoked (via `mergeRefs`).
+ *   - Wardic's keys win: the Starting style goes over the user's `style` until the first
+ *     commit; from then on the user's `style` is the fallback, without the keys the
+ *     gate holds, which Wardic writes onto the element (ADR-0034). A reactive user
+ *     `style` re-runs the spread's `style`; a frame never does.
+ *
+ * SSR-correct: {@link createWardWith} computes the Starting style synchronously, so the
+ * `<Dynamic>` renders with the merged Starting style on the very first render.
+ *
+ * REACTIVITY (component props): each motion prop is a plain VALUE, not an
+ * accessor. Solid's reactive prop getters already make a component prop tracked —
+ * reading `motion.animate` INSIDE {@link motionToConfig}'s config accessor
+ * subscribes to whatever signals back the prop. So write a TRACKED EXPRESSION as
+ * the value (`animate={open() ? { opacity: 1 } : { opacity: 0 }}`), NOT a function
+ * (`animate={() => expr}` is a type error — props are values, not accessors). A
+ * signal flip in that expression re-runs the config accessor and drives a Retarget.
+ */
+import { mergeRefs } from "@solid-primitives/refs"
+import * as Arr from "effect/Array"
+import * as Bool from "effect/Boolean"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Rec from "effect/Record"
+import * as UndefinedOr from "effect/UndefinedOr"
+import { $PROXY, type Accessor, children, type Component, createComponent, createEffect, createRenderEffect, type JSX, sharedConfig, splitProps, untrack } from "solid-js"
+import { assign, Dynamic, getNextElement, insert, spread, SVGElements, use } from "solid-js/web"
+import { isServer } from "./server.ts"
+import { GESTURE_KEYS } from "./gesture-callbacks.ts"
+import { renderServerElement, serverAppearOfWard, createWardWith, type SpineInternals, type WardStyle, type WardUserProps } from "./create-ward.tsx"
+import type { WardConfig, WardicVariantLabels } from "./config.ts"
+import type { InferredMotion, TargetKey } from "./ward-keys.ts"
+import { changesContext } from "./variant-tree.ts"
+import { MOTION_PROPS, motionToConfig, type WardicMotionProps } from "./motion-props.ts"
+import { droppedKeysOf, markWardic, routingTagOf, type WardicCreateOptions } from "./wardic-component.ts"
+import { useWardicConfig } from "./wardic-config.tsx"
+import { isValidPropOf } from "./wardic-config-value.ts"
+
+export { MOTION_PROPS, motionToConfig, type WardicMotionProps } from "./motion-props.ts"
+
+/**
+ * Props for a `wardic.<tag>` element: the tag's intrinsic props + motion props `M`, with a `style`
+ * that takes the transform keys and Live values too ({@link WardStyle}). A `wardic.<tag>`
+ * component's `M` has its keys inferred ({@link WardicComponent}).
+ */
+export type WardicProps<Tag extends keyof JSX.IntrinsicElements, M = WardicMotionProps> =
+  // `onAnimationStart` is Motion's (#257), not the DOM's CSS `animationstart` event's, as on Motion.
+  & Omit<JSX.IntrinsicElements[Tag], "style" | "onAnimationStart" | "onDrag" | "onDragStart" | "onDragEnd">
+  & M
+  & { readonly style?: WardStyle | string | undefined }
+
+/**
+ * A `wardic.<tag>` component: generic over the keys its targets set, so its `transition` takes
+ * entries for those keys, `default` and `layout`, and a target's own takes them and `default`
+ * ({@link InferredMotion}). A name an entry gives that the element doesn't animate is an error, and
+ * completion inside a `transition` offers the keys it drives.
+ */
+export type WardicComponent<Tag extends keyof JSX.IntrinsicElements> = <
+  K extends TargetKey = never,
+  N extends string = never,
+  LI extends WardicVariantLabels = never,
+  LA extends WardicVariantLabels = never,
+  D extends boolean | "x" | "y" = never,
+>(props: WardicProps<Tag, InferredMotion<WardicMotionProps, K, N, LI, LA, D>>) => JSX.Element
+
+/**
+ * The shape `wardic.create(Component)` requires of a wrapped component: it must
+ * forward `props.ref` to its single root DOM element so the spine can wire up
+ * (ADR-0008's ref-forwarding contract). All motion is committed through that
+ * ref, so the wrapped component owns its own root JSX.
+ */
+export type WardicWrappable = { ref?: (el: HTMLElement) => void }
+
+/**
+ * A client element's config from its split-off motion props: their keys are fixed unless they're a
+ * proxy (over a reactive spread), so the gesture callbacks the element wasn't given are never read
+ * (#273).
+ */
+export const configOfMotion = (motion: WardicMotionProps): Accessor<WardConfig> => motionToConfig(motion, Bool.not($PROXY in motion))
+
+/**
+ * `create(tag | Component)` of a form (`wardic.create`, `w.create`): a Wardic component, a Complete
+ * element's or a Slim one's as `kind` says (#511).
+ *
+ * Both are an element with a Ward on it, made by {@link createWardWith} (#253, as the Solid 2
+ * binding's `create` is, ADR-0045): the Starting style in `style` until the gate's first frame
+ * is committed (so on a server and in the hydration render), then the user's style (over the drag
+ * defaults) without the keys the gate holds (ADR-0034).
+ *   - `create("div")` (element-string): renders `<Dynamic component={tag}>`.
+ *   - `create(Component)` (a component function): the wrapped component must forward `props.ref`
+ *     to its single root element, where the gate commits each frame; that is the only
+ *     requirement. It also gets `style` and `draggable`: one that applies `props.style` renders
+ *     its Starting style on a server, and one that doesn't still animates, the drag defaults
+ *     set on its element at mount (ADR-0021, decision 6). One that never forwards its ref is a
+ *     clear error once mounted (ADR-0008).
+ *
+ * `options` (#443, Motion's `motion.create` options): `forwardMotionProps` hands the motion props on
+ * to what it renders as well, and `type` says what its element is for its server render and Starting
+ * style ({@link WardicCreateOptions}).
+ */
+export function createWith(arg: string | Component<Record<string, unknown> & WardicWrappable>, options: WardicCreateOptions, kind: SpineInternals): Component<Record<string, unknown>> {
+  const forward = options.forwardMotionProps === true
+  const made = Bool.match(Predicate.isString(arg), {
+    onTrue: () => wardComponent(arg as string, { ...kind, tag: routingTagOf(arg as string, options.type) }, forward),
+    onFalse: () => wardComponent(arg as Component<Record<string, unknown> & WardicWrappable>, { ...WRAPPED, ...kind, tag: routingTagOf(undefined, options.type) }, forward),
+  })
+  // Marked with what it wraps (#443): `isWardicComponent`, `unwrapWardicComponent`.
+  return markWardic(made, arg)
+}
+
+/** The `create` of a form: {@link createWith}'s overloads. */
+export interface Create {
+  <Tag extends keyof JSX.IntrinsicElements>(tag: Tag, options?: WardicCreateOptions): WardicComponent<Tag>
+  // A component's stays a plain `Component`, its keys not inferred: a generic return type would stop
+  // TS carrying a generic component's own type parameters through (Kobalte's `<T extends ValidComponent>`).
+  <P>(component: Component<P & WardicWrappable>, options?: WardicCreateOptions): Component<P & WardicMotionProps>
+  (tag: string, options?: WardicCreateOptions): Component<WardicProps<keyof JSX.IntrinsicElements>>
+}
+
+/** A form's `create`, its elements of `kind`. */
+export const createOf =
+  (kind: SpineInternals): Create =>
+  ((arg: string | Component<Record<string, unknown> & WardicWrappable>, options: WardicCreateOptions = {}) => createWith(arg, options, kind)) as Create
+
+/**
+ * A form's proxy (`wardic`, `w`): called, it's the form's directive; `create` and the form's
+ * `extras` are its properties, and `<form>.<tag>` is `create(tag)`, cached so `wardic.div ===
+ * wardic.div` (stable component identity across reads). Any non-string key is `undefined`.
+ */
+export const formOf = <F,>(directive: (el: HTMLElement, value: Accessor<WardConfig>) => void, create: Create, extras: Readonly<Record<string, unknown>>): F => {
+  const cache = new Map<string, Component<WardicProps<keyof JSX.IntrinsicElements>>>()
+  return new Proxy(directive, {
+    get(_, prop) {
+      if (prop === "create") return create
+      if (Predicate.isString(prop)) {
+        if (Object.hasOwn(extras, prop)) return extras[prop]
+        return Option.getOrElse(Option.fromUndefinedOr(cache.get(prop)), () => {
+          const c = create(prop)
+          cache.set(prop, c)
+          return c
+        })
+      }
+      return undefined
+    },
+  }) as unknown as F
+}
+
+/** What wraps a component tells {@link createWardWith}: its component may not pass `style` on. */
+const WRAPPED: SpineInternals = { defaultsOnElement: true }
+
+/** What a form's `create` renders: an element's tag, or the component it wraps. */
+type Rendered = string | Component<Record<string, unknown> & WardicWrappable>
+
+/** The namespace an svg tag's element is made in, as Solid's `createDynamic` makes it. */
+const SVG_NAMESPACE = "http://www.w3.org/2000/svg"
+
+/**
+ * What `<Dynamic component={component}>` renders, for a form's tag or component, which never changes
+ * (#525). Still a component boundary, as `Dynamic` is, so the hydration keys land where the server's
+ * `Dynamic` puts them. Without `Dynamic`'s `splitProps`, which copied every prop to take `component`
+ * out, and without `createDynamic`'s two memos over a component that can't change.
+ */
+const fixedElement = (component: Rendered): Component<Record<string, unknown>> => {
+  if (Predicate.isFunction(component)) return (props) => untrack(() => component(props))
+  const tag = component
+  const isSvg = SVGElements.has(tag)
+  return (props) => {
+    const el = tagElementOf(tag, isSvg, props)
+    spreadOnto(el, props, isSvg)
+    return el
+  }
+}
+
+/** `tag`'s element: the server's while hydrating, else a new one, as `createDynamic` makes it. */
+const tagElementOf = (tag: string, isSvg: boolean, props: Record<string, unknown>): Element => {
+  if (Predicate.isNotNullish(sharedConfig.context)) return getNextElement()
+  if (isSvg) return document.createElementNS(SVG_NAMESPACE, tag)
+  const is = untrack(() => props.is)
+  if (Predicate.isString(is)) return document.createElement(tag, { is })
+  return document.createElement(tag)
+}
+
+/**
+ * Solid's `spread` for props whose keys are fixed (#525): their children's effect only when they have
+ * children, and their ref called once, as JSX calls its own `ref`, where `spread` gives each a render
+ * effect an element. A proxy's keys can change (a reactive spread), so it takes Solid's `spread`.
+ */
+const spreadOnto = (el: Element, props: Record<string, unknown>, isSvg: boolean): void => {
+  if ($PROXY in props) {
+    spread(el, props, isSvg)
+    return
+  }
+  if ("children" in props) insert(el, () => props.children)
+  untrack(() => {
+    const ref = props.ref
+    if (Predicate.isFunction(ref)) use(ref as (node: Element) => void, el)
+  })
+  const prev = {}
+  createRenderEffect(() => assign(el, props, isSvg, true, prev, true))
+}
+
+/**
+ * `<form>.<tag>` and `<form>.create(Component)`: the element, or the wrapped component, with a
+ * Ward from {@link createWardWith} spread on it, its variant context's Provider around it when it
+ * changes what its children read (#50). `forward`: its motion props are handed on too (#443).
+ */
+const wardComponent = (component: Rendered, internal: SpineInternals, forward: boolean): Component<Record<string, unknown>> => {
+  const Rendered = fixedElement(component)
+  // What an element that can never want a gesture runs with (#525): made once a form.
+  const gestureless: SpineInternals = { ...internal, gestureless: true }
+  return (props) => {
+    // The nearest `WardicConfig`'s `isValidProp`, as the element is made (#443).
+    const isValidProp = isValidPropOf(useWardicConfig())
+    // A server render takes the lean path (ADR-0021, decision 4).
+    if (isServer) return serverElement(component, internal, props, forward, isValidProp)
+
+    // 3-way split: motion props (consumed, and only handed on when forwarded, #443), then ref+style
+    // (merged), then everything else (rest) passes through to the element or component, but a tag's
+    // props a `WardicConfig`'s `isValidProp` keeps off it.
+    const [motion, refStyle, own] = splitProps(props as WardicProps<keyof JSX.IntrinsicElements>, MOTION_PROPS, ["ref", "style"])
+    const dropped = droppedKeysOf(() => Object.keys(own), isValidProp, Predicate.isString(component))
+    // Split again only when it keeps any off (most elements have no `isValidProp` above them).
+    const rest = Bool.match(Arr.isReadonlyArrayEmpty(dropped), {
+      onTrue: () => own,
+      onFalse: () => splitProps(own, dropped as Array<keyof typeof own>)[1],
+    })
+    const handedOn = Bool.match(forward, { onTrue: () => motion, onFalse: () => NO_PROPS })
+
+    // Reactive config accessor: motionToConfig reads each (reactive) prop getter
+    // inside the accessor, so a changed `animate` / `whileHover` / `transition`
+    // (a tracked expression) drives a Retarget. The tag lets an svg-inner element
+    // render its Starting style's attribute keys as attributes (ADR-0021).
+    const cfg = configOfMotion(motion)
+    // Its keys fixed (no reactive spread) and none of them a gesture's, it can never want one (#525).
+    let spineInternal = internal
+    if (Bool.not($PROXY in motion)) {
+      if (Bool.not(Arr.some(GESTURE_KEYS, (key) => key in motion))) spineInternal = gestureless
+    }
+    const ward = createWardWith(cfg, spineInternal)
+
+    // Delegate the ref + style merge entirely to ward(): it invokes both the
+    // user's ref and ward's internal ref, and gives the element its `style`: the
+    // Starting style over the user's, then the user's without the keys the gate
+    // holds (ADR-0034).
+    //
+    // `style` is threaded as a LIVE GETTER, not a value read once at setup:
+    // `refStyle.style` is a reactive `splitProps` getter, so a reactive user
+    // `style` prop (e.g. `style={{ left: pos() }}` on a non-animated key) is
+    // tracked by ward()'s reactive style getter and re-merged on change. Reading
+    // it into a `const` here would freeze it at its initial value. `ref` is wired
+    // once at mount (refs don't change), so it stays a one-time read.
+    const forwarding = forwardingOf(component, (refStyle as { ref?: (el: HTMLElement) => void }).ref)
+    const ref = forwarding.ref
+    const userProps: WardUserProps = {
+      ...UndefinedOr.match(ref, { onUndefined: () => ({}), onDefined: (defined) => ({ ref: defined }) }),
+      get style() {
+        return (refStyle as { style?: JSX.CSSProperties }).style
+      },
+    }
+
+    // An element that changes what its children read renders its variant context's Provider
+    // around them (#50); any other renders none (`changesContext`, decided once, as on a server).
+    // The Ward's props, made once: a call spread in JSX compiles to a function source, which made
+    // `mergeProps` a proxy that the spread read every key through (#525). Their `style` is a getter.
+    const wardProps = ward(userProps)
+    const element = (): JSX.Element => <Rendered {...handedOn} {...rest} {...wardProps} />
+    return Bool.match(changesContext(untrack(cfg)), {
+      onFalse: () => forwarding.render(element),
+      onTrue: () => <ward.Provider>{forwarding.render(element)}</ward.Provider>,
+    })
+  }
+}
+
+/** The user's ref, merged with what checks the Ward's, and how the element renders. */
+interface Forwarding {
+  readonly ref: ((el: HTMLElement) => void) | undefined
+  readonly render: (element: () => JSX.Element) => JSX.Element
+}
+
+/** A tag's: the user's ref, and its element as it is. */
+const ownElement = (element: () => JSX.Element): JSX.Element => element()
+
+/**
+ * The user's ref, and, for a wrapped component, the check that it forwards the Ward's (ADR-0008,
+ * narrowed by #414): one that renders an element and forwards its ref to none of what it renders
+ * leaves the gate no element to commit to, a clear error. One that renders nothing yet (a component
+ * library's part that shows only while open or selected) is waited on: its element is driven when it
+ * comes. Checked each time what it renders changes, inside the wrap's Provider (#50).
+ */
+const forwardingOf = (component: Rendered, userRef: ((el: HTMLElement) => void) | undefined): Forwarding => {
+  if (Predicate.isString(component)) return { ref: userRef, render: ownElement }
+  let reached: HTMLElement | undefined
+  const ref = mergeRefs(userRef, (el: HTMLElement) => {
+    reached = el
+  })
+  const render = (element: () => JSX.Element): JSX.Element => {
+    const rendered = children(element)
+    createEffect(() => {
+      const elements = Arr.filter(rendered.toArray(), isElement)
+      if (Arr.isArrayEmpty(elements)) return
+      if (Arr.some(elements, (inside) => Predicate.isNotUndefined(reached) && inside.contains(reached))) return
+      const name = component.name || "anonymous component"
+      throw new Error(
+        `wardic.create(${name}): the wrapped component rendered an element but did not forward its ref to it. ` +
+          "The component must forward props.ref to a single root DOM element " +
+          "(e.g. <div ref={props.ref}>...</div>). Element-only motion is wired through the ref.",
+      )
+    })
+    return rendered as unknown as JSX.Element
+  }
+  return { ref, render }
+}
+
+/** Whether a rendered node is an element. */
+const isElement = (node: unknown): node is Element => node instanceof Element
+
+/** No props: what an element that doesn't forward its motion props hands on of them. */
+const NO_PROPS: Readonly<Record<string, never>> = {}
+
+/** The motion props, as a set for the server path's one pass. */
+const MOTION_KEYS: ReadonlySet<string> = new Set(MOTION_PROPS)
+
+/**
+ * Set each of `values` on `out` as a plain data property. A key copied from the user's props
+ * may be a getter (a reactive prop like `cx={cx()}`), which an assignment can't overwrite;
+ * Wardic's value wins, as `mergeProps` makes it on the client.
+ */
+const override = (out: Record<string, unknown>, values: Record<string, unknown>): void =>
+  Arr.forEach(Rec.keys(values), (key) => {
+    Object.defineProperty(out, key, { value: values[key], enumerable: true, configurable: true, writable: true })
+  })
+
+/**
+ * Everything in `props` but `ref`, `style`, the motion props unless `forward`, and the keys `dropped`
+ * (#443), in one pass; getters stay getters.
+ */
+const passThrough = (props: Record<string, unknown>, forward: boolean, dropped: ReadonlyArray<string>): Record<string, unknown> => {
+  const descriptors = Object.getOwnPropertyDescriptors(props)
+  const out: Record<string, unknown> = {}
+  const off = new Set(dropped)
+  Arr.forEach(Rec.keys(descriptors), (key) => {
+    if (key === "ref" || key === "style" || off.has(key)) return
+    if (MOTION_KEYS.has(key) && !forward) return
+    Object.defineProperty(out, key, UndefinedOr.getOrThrow(descriptors[key]))
+  })
+  return out
+}
+
+/**
+ * `wardic.<tag>` and `wardic.create(Component)` during a server render (ADR-0021, decisions 4 and
+ * 6): the element, or the component, with its Starting style and static attributes, built in one
+ * pass over the props. Solid's server `splitProps` and `mergeProps` cost most of a wrapped
+ * element's server time, and none of their reactivity matters there. The client's
+ * `createUniqueId` (inside `createWardWith`) and its `Dynamic` boundary are kept, so every
+ * hydration key lands where the client's render puts it.
+ */
+const serverElement = (
+  component: Rendered,
+  internal: SpineInternals,
+  props: Record<string, unknown>,
+  forward: boolean,
+  isValidProp: ((key: string) => boolean) | undefined,
+): JSX.Element => {
+  // A tag's props `isValidProp` keeps off it, as the client's (#443): of its own, the motion props, `ref` and `style` aside.
+  const ownKeys = (): ReadonlyArray<string> => Arr.filter(Object.keys(props), (key) => !MOTION_KEYS.has(key) && key !== "ref" && key !== "style")
+  const out = passThrough(props, forward, droppedKeysOf(ownKeys, isValidProp, Predicate.isString(component)))
+  const cfg = motionToConfig(props as WardicMotionProps)
+  const ward = createWardWith(cfg, internal)
+  override(out, { ...ward({ style: props.style as JSX.CSSProperties | undefined }), component })
+  // The client's nesting: the element's `ward.Provider` when it changes what its children read
+  // (#50), then the element; a late chunk's root then its chunk's style (#245).
+  const element = (): JSX.Element => createComponent(Dynamic, out as Parameters<typeof Dynamic>[0])
+  const render = (): JSX.Element =>
+    Bool.match(changesContext(cfg()), {
+      onFalse: element,
+      onTrue: () =>
+        createComponent(ward.Provider, {
+          get children() {
+            return element()
+          },
+        }),
+    })
+  return renderServerElement(serverAppearOfWard(ward), render)
+}
+

package/src/feature-section.ts

@@ -0,0 +1,33 @@
+/**
+ * A section's **Features** (#511, ADR-0067), for the Solid 1 binding: the context each `LazyWardic`
+ * puts its section in (`feature.ts`'s `makeSection`), so a Slim element has its provider's Features
+ * and every `LazyWardic`'s between them (decision 2). A provider's own section isn't in it: the
+ * provider keeps it (`provider.tsx`), so a provider renders no second context, and every hydration
+ * key stays where it was.
+ *
+ * @module
+ */
+import type * as Cause from "effect/Cause"
+import { createContext, onCleanup, useContext } from "solid-js"
+import { type FeatureRegistry, type FeatureSection, type FeaturesProp, makeSection, type SectionHost } from "./feature.ts"
+import { isServer } from "./server.ts"
+import { reactivity } from "./solid-reactivity.ts"
+
+const FeatureSectionContext = createContext<FeatureSection | undefined>(undefined)
+
+/** The nearest `LazyWardic`'s section, or `undefined` under none: its provider's then. */
+export const useLazySection = (): FeatureSection | undefined => useContext(FeatureSectionContext)
+
+/** The Provider a `LazyWardic`'s subtree renders under. */
+export const FeatureSectionProvider = FeatureSectionContext.Provider
+
+const HOST: SectionHost = { reactivity, server: isServer, onCleanup }
+
+/** A section under `parent`, made under the current owner (`feature.ts`'s `makeSection`). */
+export const sectionUnder = (
+  parent: FeatureSection,
+  registry: FeatureRegistry,
+  prop: FeaturesProp | undefined,
+  strict: boolean,
+  report: (cause: Cause.Cause<unknown>) => void,
+): FeatureSection => makeSection(parent, registry, prop, strict, report, HOST)