@zerotal/flow 1.0.0

package/src/decorators.ts

@@ -0,0 +1,978 @@
+// ── Decorator metadata registries ─────────────────────────────────────────────
+//
+// Standard TC39 decorators, keyed by the class prototype; the `get*` readers walk the
+// prototype chain so subclasses inherit.
+//
+// METHOD / GETTER decorators (@computed, @expose on a method, @renderless, @on) register
+// via `addInitializer`, which Bun compiles correctly.
+//
+// FIELD decorators (@expose on a field, @locked, @reactive, @modelable, @transient,
+// @validate, @url, @session) CANNOT defer to a field initializer or to `addInitializer`:
+// Bun 1.3.x cross-wires those across every class defined in one file (a class runs another
+// class's initializers, and a name captured in the closure resolves to the LAST class in
+// the file). The only reliable signal is the decorator BODY, which runs synchronously with
+// the correct `context.name`. So field decorators capture {name, apply} into a module
+// buffer at definition time; the buffer is drained lazily the first time a `get*` reader is
+// called for a class — we construct a probe instance to learn that class's own field names
+// and match the buffered entries by name (see `_drainFields`).
+
+import type { RuleBuilder, FieldRule } from "@zerotal/validator";
+import type { LooseEventName } from "./events.ts";
+
+/**
+ * A `@validate` rule: a callback that receives the validator's chain API and returns the built
+ * field rule. This is the value passed to the {@link validate} decorator and the shape of each
+ * entry in {@link ValidationRules}.
+ *
+ * @example
+ * ```ts
+ * const nameRule: ValidateBuilder = (rule) => rule.required().min(2).max(50);
+ * ```
+ *
+ * @category Validation
+ */
+export type ValidateBuilder = (rule: RuleBuilder) => FieldRule;
+
+const _computedProtos = new WeakMap<object, Set<string>>();
+const _transientProtos = new WeakMap<object, Set<string>>();
+const _exposedProps = new WeakMap<object, Set<string>>();
+const _exposedMethods = new WeakMap<object, Set<string>>();
+const _lockedProps = new WeakMap<object, Set<string>>();
+const _renderlessMethods = new WeakMap<object, Set<string>>();
+const _validateRules = new WeakMap<object, Map<string, ValidateBuilder>>();
+const _onListeners = new WeakMap<object, Map<string, string>>();
+const _urlProps = new WeakMap<object, Map<string, UrlOptions>>();
+/**
+ * prop -> where its value comes from:
+ *   undefined  — the property's own name is the segment
+ *   string     — that segment
+ *   class      — whichever segment resolved to an instance of it
+ */
+const _routeParamProps = new WeakMap<object, Map<string, ParamSource>>();
+const _sessionProps = new WeakMap<object, Map<string, SessionOptions>>();
+const _reactiveProps = new WeakMap<object, Set<string>>();
+const _modelableProps = new WeakMap<object, Set<string>>();
+const _taskMethods = new WeakMap<object, Set<string>>();
+const _presenceProps = new WeakMap<object, Map<string, PresenceChannel>>();
+const _sharedProps = new WeakMap<object, Map<string, SharedChannel>>();
+
+function _register(map: WeakMap<object, Set<string>>, proto: object, key: string): void {
+  let s = map.get(proto);
+  if (!s) {
+    s = new Set();
+    map.set(proto, s);
+  }
+  s.add(key);
+}
+
+function _registerMap<V>(
+  map: WeakMap<object, Map<string, V>>,
+  proto: object,
+  key: string,
+  value: V,
+): void {
+  let m = map.get(proto);
+  if (!m) {
+    m = new Map();
+    map.set(proto, m);
+  }
+  m.set(key, value);
+}
+
+function _collect(map: WeakMap<object, Set<string>>, startProto: object): Set<string> {
+  const result = new Set<string>();
+  let proto: object | null = startProto;
+  while (proto && proto !== Object.prototype) {
+    const s = map.get(proto);
+    if (s) for (const k of s) result.add(k);
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  return result;
+}
+
+function _collectMap<V>(map: WeakMap<object, Map<string, V>>, startProto: object): Map<string, V> {
+  const result = new Map<string, V>();
+  let proto: object | null = startProto;
+  while (proto && proto !== Object.prototype) {
+    const m = map.get(proto);
+    if (m) for (const [k, v] of m) if (!result.has(k)) result.set(k, v);
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  return result;
+}
+
+/** Register against the instance's own prototype (from an initializer/addInitializer). */
+function _registerOn(map: WeakMap<object, Set<string>>, self: unknown, key: string): void {
+  _register(map, Object.getPrototypeOf(self as object) as object, key);
+}
+
+// ── Field-decorator buffer (Bun standard-decorator workaround) ────────────────
+
+interface PendingField {
+  name: string;
+  apply: (proto: object) => void;
+}
+const _pendingFields: PendingField[] = [];
+const _drainedProtos = new WeakSet<object>();
+
+/** Enqueue a field registration captured (with the correct name) in the decorator body. */
+function _enqueueField(name: string, apply: (proto: object) => void): void {
+  _pendingFields.push({ name, apply });
+}
+
+/**
+ * Drain the buffered field registrations belonging to `ctor` onto its prototype. Called
+ * lazily by the readers. We construct a throwaway instance to discover the class's own field
+ * names IN DECLARATION ORDER (`Object.keys`), then claim the longest contiguous run of buffered
+ * entries whose names map to STRICTLY INCREASING positions in that order. A class's field
+ * decorators run consecutively at definition time (including a subclass's mixin-supplied fields)
+ * and in declaration order, so its block is exactly such a run.
+ *
+ * The strictly-increasing constraint is what makes this robust when two classes share field
+ * names AND their blocks are adjacent in the buffer (e.g. AddTransactionModal and TransferModal
+ * both declare `accountId`/`open`/`fAmount`). A plain "longest run ⊆ own" would greedily extend
+ * one class's run into the neighbour's leading shared fields; but those shared names map to
+ * EARLIER positions in this class's declaration order, so the increasing check stops the run at
+ * the true block boundary. Keeps multiple decorators on one field (e.g. `@expose @url page`)
+ * together (same name → same index, but they're adjacent duplicates — handled by allowing equal
+ * only when it's the identical consecutive name).
+ */
+function _drainFields(ctor: unknown): void {
+  if (typeof ctor !== "function") return;
+  const proto = (ctor as { prototype?: object }).prototype;
+  if (!proto || _drainedProtos.has(proto)) return;
+  _drainedProtos.add(proto); // mark first to stay re-entrancy-safe during the probe
+  if (_pendingFields.length === 0) return;
+
+  let ownIndex: Map<string, number>;
+  try {
+    const keys = Object.keys(new (ctor as new () => object)());
+    ownIndex = new Map(keys.map((k, i) => [k, i]));
+  } catch {
+    return; // not constructible without args — nothing we can match
+  }
+
+  // Longest contiguous run whose names map to strictly-increasing declaration-order indices
+  // (equal allowed only for an identical repeated name — multiple decorators on one field).
+  let bestStart = -1;
+  let bestLen = 0;
+  for (let i = 0; i < _pendingFields.length; i++) {
+    if (!ownIndex.has(_pendingFields[i]!.name)) continue;
+    let last = -1;
+    let lastName = "";
+    let j = i;
+    while (j < _pendingFields.length) {
+      const name = _pendingFields[j]!.name;
+      const idx = ownIndex.get(name);
+      if (idx === undefined) break;
+      if (idx < last || (idx === last && name !== lastName)) break;
+      last = idx;
+      lastName = name;
+      j++;
+    }
+    if (j - i > bestLen) {
+      bestLen = j - i;
+      bestStart = i;
+    }
+  }
+  if (bestStart === -1) return;
+  const claimed = _pendingFields.splice(bestStart, bestLen);
+  for (const e of claimed) e.apply(proto);
+}
+
+/** Drain via an instance or a prototype before reading. */
+function _ensureDrained(target: object): void {
+  // target may be an instance (use its constructor) or a prototype (use .constructor).
+  const ctor = (target as { constructor?: unknown }).constructor;
+  if (typeof ctor !== "function") {
+    _drainFields(ctor);
+    return;
+  }
+  // Drain base-most ancestor → derived, so fields DECLARED on a base class register
+  // on the *base* prototype (shared by every subclass) instead of on whichever
+  // subclass is constructed first. Without this, sibling subclasses of a decorated
+  // base (e.g. one generated page class per admin resource) never inherit the base's
+  // @url/@expose/@locked props, so their URL/state binding silently breaks.
+  const chain: unknown[] = [];
+  for (
+    let c: unknown = ctor;
+    typeof c === "function" && (c as { prototype?: object }).prototype;
+    c = Object.getPrototypeOf(c)
+  ) {
+    chain.unshift(c);
+  }
+  for (const cls of chain) _drainFields(cls);
+}
+
+// Field decorators capture their name+registration in the BODY (correct name) and enqueue
+// it; they do NOT transform the field, so the field's own initializer (default value) runs
+// unchanged. Registration happens later, on first read, via `_drainFields`.
+function _fieldDecorator(
+  register: (proto: object, name: string) => void,
+): (value: unknown, context: ClassFieldDecoratorContext) => void {
+  return (_value, context) => {
+    const name = String(context.name);
+    _assertField(name, context);
+    _enqueueField(name, (proto) => register(proto, name));
+  };
+}
+
+/**
+ * Reject a field-style decorator applied to a getter/setter/accessor. A `@computed`
+ * getter (and any accessor) has no writable snapshot storage, so `@locked`/`@expose`/…
+ * on it would serialize a value the framework then tries to write back on update —
+ * clobbering the getter. TypeScript already flags this (the decorator's context type
+ * excludes getters), but Bun runs code without typechecking, so guard at runtime too.
+ */
+function _assertField(name: string, context: { kind: string }): void {
+  if (context.kind !== "field") {
+    throw new Error(
+      `[Flow] "${name}" — @locked/@url/@session/@transient/@reactive/@modelable can only ` +
+        `decorate a field, not a ${context.kind}. A getter isn't stored in the snapshot; ` +
+        `use @computed for a derived value (it renders as static server text).`,
+    );
+  }
+}
+
+export function getComputedKeys(instance: object): Set<string> {
+  return _collect(_computedProtos, Object.getPrototypeOf(instance) as object);
+}
+export function getTransientKeys(instance: object): Set<string> {
+  _ensureDrained(instance);
+  return _collect(_transientProtos, Object.getPrototypeOf(instance) as object);
+}
+export function getExposedProps(instance: object): Set<string> {
+  _ensureDrained(instance);
+  return _collect(_exposedProps, Object.getPrototypeOf(instance) as object);
+}
+export function getLockedProps(instance: object): Set<string> {
+  _ensureDrained(instance);
+  return _collect(_lockedProps, Object.getPrototypeOf(instance) as object);
+}
+export function getExposedMethods(PageClass: { prototype: object }): Set<string> {
+  return _collect(_exposedMethods, PageClass.prototype as object);
+}
+/** `@task` method names — streaming, cancellable long-running actions. */
+export function getTaskMethods(PageClass: { prototype: object }): Set<string> {
+  return _collect(_taskMethods, PageClass.prototype as object);
+}
+export function getRenderlessMethods(PageClass: { prototype: object }): Set<string> {
+  return _collect(_renderlessMethods, PageClass.prototype as object);
+}
+export function getValidateRules(instance: object): Map<string, ValidateBuilder> {
+  _ensureDrained(instance);
+  return _collectMap(_validateRules, Object.getPrototypeOf(instance) as object);
+}
+export function getListeners(PageClass: { prototype: object }): Map<string, string> {
+  return _collectMap(_onListeners, PageClass.prototype as object);
+}
+export function getUrlProps(instance: object): Map<string, UrlOptions> {
+  _ensureDrained(instance);
+  return _collectMap(_urlProps, Object.getPrototypeOf(instance) as object);
+}
+export function getSessionProps(instance: object): Map<string, SessionOptions> {
+  _ensureDrained(instance);
+  return _collectMap(_sessionProps, Object.getPrototypeOf(instance) as object);
+}
+
+/**
+ * The session key a `@session` field reads and writes.
+ *
+ * Plain by default — `@session userId` is the session's own `userId`, the same value any
+ * controller or other component sees. `scoped: true` namespaces it to the component instead,
+ * for state that belongs to this one page and should not collide with anything else.
+ */
+export function sessionKeyFor(prop: string, opts: SessionOptions, componentName: string): string {
+  const key = opts.key ?? prop;
+  return opts.scoped ? `flow:${componentName}:${key}` : key;
+}
+/** Reactive-prop names. Accepts a prototype directly (e.g. ChildClass.prototype). */
+export function getReactiveProps(proto: object): Set<string> {
+  _ensureDrained(proto);
+  return _collect(_reactiveProps, proto);
+}
+/** Modelable-prop names. Accepts a prototype directly (e.g. ChildClass.prototype). */
+export function getModelableProps(proto: object): Set<string> {
+  _ensureDrained(proto);
+  return _collect(_modelableProps, proto);
+}
+/** `@presence` props → their channel resolver, for the instance's class. */
+export function getPresenceProps(instance: object): Map<string, PresenceChannel> {
+  _ensureDrained(instance);
+  return _collectMap(_presenceProps, Object.getPrototypeOf(instance) as object);
+}
+/** `@shared` props → their channel resolver, for the instance's class. */
+export function getSharedProps(instance: object): Map<string, SharedChannel> {
+  _ensureDrained(instance);
+  return _collectMap(_sharedProps, Object.getPrototypeOf(instance) as object);
+}
+
+// ── @computed ─────────────────────────────────────────────────────────────────
+
+/** Wrap a getter so it memoizes its result while a render pass is active. */
+function _memoizeGetter(orig: () => unknown, name: string): () => unknown {
+  return function (this: Record<string, unknown>): unknown {
+    if (!this["__flowComputing"]) return orig.call(this); // only cache during render
+    let cache = this["__flowComputed"] as Map<string, unknown> | undefined;
+    if (!cache) {
+      cache = new Map();
+      this["__flowComputed"] = cache;
+    }
+    if (cache.has(name)) return cache.get(name);
+    const v = orig.call(this);
+    cache.set(name, v);
+    return v;
+  };
+}
+
+/**
+ * Marks a getter as computed — a value derived from other state, excluded from the snapshot.
+ *
+ * @remarks
+ * A computed getter is not serialized and is not client-writable; it renders as static
+ * server-produced text. The result is memoized for the duration of a single render pass
+ * (Livewire-style per-request caching): an expensive getter read several times in one template
+ * runs once. The cache is scoped to the active render (see `_renderFlowPage`), so reads
+ * outside rendering always recompute and never go stale. Apply only to a getter — a field-style
+ * decorator on it is rejected; conversely `@computed` on a non-getter is a TypeScript error.
+ *
+ * @example
+ * ```tsx
+ * class Cart extends Component {
+ *   @expose items: LineItem[] = [];
+ *
+ *   @computed get total(): number {
+ *     return this.items.reduce((sum, i) => sum + i.price * i.qty, 0);
+ *   }
+ * }
+ * ```
+ *
+ * @category Reactivity
+ */
+export function computed<This, Return>(
+  getter: (this: This) => Return,
+  context: ClassGetterDecoratorContext<This, Return>,
+): (this: This) => Return {
+  const name = String(context.name);
+
+  context.addInitializer(function (this: This) {
+    _registerOn(_computedProtos, this, name);
+  });
+  return _memoizeGetter(getter, name) as (this: This) => Return;
+}
+
+// ── @transient ────────────────────────────────────────────────────────────────
+
+/**
+ * Marks a field as transient — excluded from the snapshot entirely.
+ *
+ * @remarks
+ * Unlike `@computed` (which is derived and re-runs each render), a transient field is ordinary
+ * server-side state that simply never crosses the wire and is not persisted between requests:
+ * it holds its default value at the start of each render and is invisible to the client. Use it
+ * for server-only scratch state (caches, handles, injected services) that must not be serialized.
+ * Applies only to a field; a getter/accessor is rejected at runtime.
+ *
+ * @example
+ * ```tsx
+ * class Report extends Component {
+ *   // Server-only handle — never serialized to the client.
+ *   @transient private db!: DatabaseConnection;
+ * }
+ * ```
+ *
+ * @category Exposure & state
+ */
+export const transient = _fieldDecorator((proto, name) => _register(_transientProtos, proto, name));
+
+// ── @expose ───────────────────────────────────────────────────────────────────
+
+type ExposeContext = ClassFieldDecoratorContext | ClassMethodDecoratorContext;
+
+/**
+ * The opt-in network boundary: makes a member reachable from the client and crosses the wire.
+ *
+ * @remarks
+ * On a **field**, the property is included in the snapshot and is mutable by the client (e.g. via
+ * `flow:model`), so it round-trips both directions. On a **method**, the method becomes callable
+ * from the browser over the WebSocket as an action. Nothing not marked (directly or via a
+ * decorator that implies it, such as `@locked`, `@task`, `@on`, `@reactive`, `@modelable`,
+ * `@presence`, `@shared`) is exposed. Rejected on a getter/accessor — use `@computed` for a
+ * derived value, or an `@expose` field for client-writable state.
+ *
+ * @example
+ * ```tsx
+ * class Counter extends Component {
+ *   @expose count = 0;
+ *
+ *   @expose increment() {
+ *     this.count++;
+ *   }
+ * }
+ * ```
+ *
+ * @category Exposure & state
+ */
+export function expose(_value: unknown, context: ExposeContext): void {
+  const name = String(context.name);
+  const kind = (context as { kind: string }).kind;
+  if (kind !== "field" && kind !== "method") {
+    throw new Error(
+      `[Flow] @expose can only decorate a field or a method, not a ${kind} ("${name}"). ` +
+        `A getter isn't stored in the snapshot; use @computed for a derived value ` +
+        `(it renders as static server text), or an @expose field for client-writable state.`,
+    );
+  }
+  if (context.kind === "field") {
+    // Field: capture in the body and enqueue (see _fieldDecorator / _drainFields).
+    _enqueueField(name, (proto) => _register(_exposedProps, proto, name));
+    return;
+  }
+  // Method: addInitializer is available (and reliable) on method contexts.
+  context.addInitializer(function (this: unknown) {
+    _registerOn(_exposedMethods, this, name);
+  });
+}
+
+// ── @locked ───────────────────────────────────────────────────────────────────
+
+/**
+ * Marks a field as exposed but read-only client-side: it is included in the snapshot (the client
+ * can read/render it) but the client cannot mutate it via `flow:model`.
+ *
+ * @remarks
+ * `@locked` implies `@expose` (it registers the prop as exposed) while additionally flagging it
+ * as locked, so client-originated writes are rejected. Use it for server-authoritative state the
+ * UI displays but must not change directly — the value only moves via server actions. Applies to
+ * a field only.
+ *
+ * @example
+ * ```tsx
+ * class Profile extends Component {
+ *   // Client renders it, but cannot bind it with flow:model.
+ *   @locked role = "member";
+ * }
+ * ```
+ *
+ * @category Exposure & state
+ */
+export const locked = _fieldDecorator((proto, name) => {
+  _register(_exposedProps, proto, name);
+  _register(_lockedProps, proto, name);
+});
+
+// ── @presence ─────────────────────────────────────────────────────────────────
+// Binds a property to a broadcast presence channel: the framework keeps it filled
+// with the live member list (who's here), updating on join/leave. The channel is
+// resolved per-instance — a static string, or a `(self) => string` for dynamic rooms.
+// The prop is server-controlled (locked): in the snapshot, not client-writable.
+
+/**
+ * A presence channel identifier: either a static channel name, or a resolver called with the
+ * component instance to compute a per-instance name (for dynamic rooms).
+ *
+ * @category Realtime
+ */
+export type PresenceChannel = string | ((self: Record<string, any>) => string);
+
+/**
+ * Binds a field to a broadcast presence channel — the framework keeps it filled with the live
+ * member list (who's here), updating on join/leave.
+ *
+ * @remarks
+ * The channel is resolved per-instance: pass a static string, or a `(self) => string` resolver
+ * for dynamic rooms. The bound prop is server-controlled — like `@locked`, it is included in the
+ * snapshot but is not client-writable. Applies to a field only.
+ *
+ * @param channel - The channel name, or a resolver over the component instance.
+ * @returns A field decorator that registers the presence binding.
+ *
+ * @example
+ * ```tsx
+ * class RoomHeader extends Component {
+ *   @presence((self) => `room.${self.roomId}`)
+ *   members: PresenceMember[] = [];
+ *
+ *   @locked roomId = "";
+ * }
+ * ```
+ *
+ * @category Realtime
+ */
+export function presence(
+  channel: PresenceChannel,
+): (value: unknown, context: ClassFieldDecoratorContext) => void {
+  return _fieldDecorator((proto, name) => {
+    _registerMap(_presenceProps, proto, name, channel);
+    // Serialized + read-only client-side, like @locked.
+    _register(_exposedProps, proto, name);
+    _register(_lockedProps, proto, name);
+  });
+}
+
+/** Resolve a `@presence` channel for a component instance (adds no prefix). */
+export function resolvePresenceChannel(channel: PresenceChannel, instance: object): string {
+  return typeof channel === "function" ? channel(instance as Record<string, unknown>) : channel;
+}
+
+// ── @shared ─────────────────────────────────────────────────────────────────
+// Binds a property to convergent, server-authoritative shared state on a broadcast
+// channel: mutating it in an action writes to a per-channel room store and broadcasts
+// to the channel, so every other subscriber's component re-reads and converges. The
+// channel resolves per-instance (a static string, or `(self) => string` for dynamic
+// rooms), the same shape as @presence — so one "room" channel can carry both who's-here
+// (@presence) and shared state (@shared). Serialized + read-only client-side (@locked):
+// clients render it but can only change it through @expose actions (last-write-wins).
+
+/**
+ * A shared-state channel identifier: either a static channel name, or a resolver called with the
+ * component instance to compute a per-instance name (for dynamic rooms).
+ *
+ * @category Realtime
+ */
+export type SharedChannel = string | ((self: Record<string, any>) => string);
+
+/**
+ * Binds a field to convergent, server-authoritative shared state on a broadcast channel.
+ *
+ * @remarks
+ * Mutating the field inside an action writes to a per-channel room store and broadcasts to the
+ * channel, so every other subscriber's component re-reads and converges (last-write-wins). The
+ * channel resolves per-instance (a static string, or `(self) => string` for dynamic rooms) — the
+ * same shape as {@link presence}, so one "room" channel can carry both who's-here (`@presence`)
+ * and shared state (`@shared`). Serialized and read-only client-side (like `@locked`): clients
+ * render it but can only change it through `@expose` actions. Applies to a field only.
+ *
+ * @param channel - The channel name, or a resolver over the component instance.
+ * @returns A field decorator that registers the shared-state binding.
+ *
+ * @example
+ * ```tsx
+ * class Whiteboard extends Component {
+ *   @shared((self) => `board.${self.boardId}`)
+ *   strokes: Stroke[] = [];
+ *
+ *   @locked boardId = "";
+ *
+ *   @expose addStroke(stroke: Stroke) {
+ *     this.strokes = [...this.strokes, stroke]; // broadcasts to every subscriber
+ *   }
+ * }
+ * ```
+ *
+ * @category Realtime
+ */
+export function shared(
+  channel: SharedChannel,
+): (value: unknown, context: ClassFieldDecoratorContext) => void {
+  return _fieldDecorator((proto, name) => {
+    _registerMap(_sharedProps, proto, name, channel);
+    // Serialized + read-only client-side, like @locked — writes go through actions.
+    _register(_exposedProps, proto, name);
+    _register(_lockedProps, proto, name);
+  });
+}
+
+/** Resolve a `@shared` channel for a component instance (adds no prefix). */
+export function resolveSharedChannel(channel: SharedChannel, instance: object): string {
+  return typeof channel === "function" ? channel(instance as Record<string, unknown>) : channel;
+}
+
+// ── @reactive ───────────────────────────────────────────────────────────────
+// A child-component prop the PARENT can push new values into on every re-render.
+// Included in the snapshot and client-writable (so the framework can deliver
+// parent updates), and re-emitted by the parent so the child re-renders when the
+// bound value changes. Mirrors Livewire's #[Reactive].
+
+/**
+ * Marks a child-component prop as reactive — the parent re-pushes new values into it on every
+ * re-render.
+ *
+ * @remarks
+ * The prop is included in the snapshot and is client-writable (so the framework can deliver the
+ * parent's updates), and the parent re-emits it so the child re-renders when the bound value
+ * changes. This is a one-way parent→child binding; use `@modelable` for two-way. Mirrors
+ * Livewire's `#[Reactive]`. Applies to a field only.
+ *
+ * @example
+ * ```tsx
+ * class PriceTag extends Component {
+ *   // Re-pushed by the parent whenever the parent's bound value changes.
+ *   @reactive amount = 0;
+ * }
+ * ```
+ *
+ * @category Reactivity
+ */
+export const reactive = _fieldDecorator((proto, name) => {
+  _register(_exposedProps, proto, name);
+  _register(_reactiveProps, proto, name);
+});
+
+// ── @modelable ────────────────────────────────────────────────────────────────
+// A reactive prop that ALSO syncs back to the parent: `value={this.x}` on a child
+// component binds the parent's `x` to the child's modelable prop both ways. Mirrors
+// Livewire's #[Modelable]. A modelable prop is implicitly reactive.
+
+/**
+ * Marks a child-component prop as two-way bound to the parent (parent↔child).
+ *
+ * @remarks
+ * A modelable prop is reactive (the parent pushes new values in on re-render) AND syncs back:
+ * `value={this.x}` on a child component binds the parent's `x` to the child's modelable prop in
+ * both directions. A modelable prop is implicitly reactive (it registers as both). Mirrors
+ * Livewire's `#[Modelable]`. Applies to a field only.
+ *
+ * @example
+ * ```tsx
+ * class TextField extends Component {
+ *   // Parent binds with `value={this.query}`; edits here flow back to the parent.
+ *   @modelable value = "";
+ * }
+ * ```
+ *
+ * @category Reactivity
+ */
+export const modelable = _fieldDecorator((proto, name) => {
+  _register(_exposedProps, proto, name);
+  _register(_reactiveProps, proto, name);
+  _register(_modelableProps, proto, name);
+});
+
+// ── @renderless ───────────────────────────────────────────────────────────────
+
+/**
+ * Marks an action method as renderless — the action runs on the server but the follow-up
+ * re-render is skipped.
+ *
+ * @remarks
+ * Unlike `@task`, `@renderless` does NOT imply `@expose` — it only registers the method as
+ * renderless, so it must be combined with `@expose` (or another decorator that exposes it) to be
+ * callable from the client. Use it for side-effect-only actions whose result the UI does not need
+ * to reflect (logging, fire-and-forget writes), avoiding the cost of a re-render and patch.
+ * Applies to a method only.
+ *
+ * @example
+ * ```tsx
+ * class Analytics extends Component {
+ *   @expose @renderless track(event: string) {
+ *     this.logger.record(event); // no DOM update needed
+ *   }
+ * }
+ * ```
+ *
+ * @category Actions
+ */
+export function renderless(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  context.addInitializer(function (this: unknown) {
+    _registerOn(_renderlessMethods, this, String(context.name));
+  });
+}
+
+// ── @task ───────────────────────────────────────────────────────────────────────
+// A long-running, cancellable action whose incremental field writes stream to the client.
+// While a @task runs, the framework flushes throttled partial patches — so `this.answer +=
+// token` appears live — keeps the triggering control in its loading state for the whole
+// duration, and exposes `this.signal` (an AbortSignal) that `this.cancel()` on the client
+// trips for cooperative cancellation. Auto-@expose (callable from the browser).
+
+/**
+ * Marks an async method as a streaming, cancellable task. Implicitly `@expose` (callable from the
+ * browser).
+ *
+ * @remarks
+ * While a `@task` runs, the framework flushes throttled partial patches — so incremental field
+ * writes such as `this.answer += token` appear live in the client — keeps the triggering control
+ * in its loading state for the whole duration, and exposes `this.signal` (an `AbortSignal`) that
+ * `this.cancel()` on the client trips for cooperative cancellation. Because it auto-exposes, no
+ * separate `@expose` is needed. Applies to a (typically async) method.
+ *
+ * @example
+ * ```tsx
+ * class Chat extends Component {
+ *   @expose answer = "";
+ *
+ *   @task async ask(prompt: string) {
+ *     for await (const token of streamCompletion(prompt, this.signal)) {
+ *       this.answer += token; // each write streams to the client
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @category Actions
+ */
+export function task(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  context.addInitializer(function (this: unknown) {
+    const proto = Object.getPrototypeOf(this as object) as object;
+    const name = String(context.name);
+    _register(_exposedMethods, proto, name);
+    _register(_taskMethods, proto, name);
+  });
+}
+
+// ── @validate ─────────────────────────────────────────────────────────────────
+
+/**
+ * Attaches a validation rule to a field using the framework validator's fluent chain.
+ *
+ * @remarks
+ * The rule is read by `this.validate()` (called with no argument) and by real-time validation on
+ * client update. `@validate` only registers the rule — it does not expose the field, so pair it
+ * with `@expose` for client-editable inputs. Applies to a field only. The decorator-attached
+ * rules mirror the object form accepted by `this.validate({ ... })` (see {@link ValidationRules}).
+ *
+ * @param build - A {@link ValidateBuilder} that builds the field rule from the chain API.
+ * @returns A field decorator that registers the rule.
+ *
+ * @example
+ * ```tsx
+ * class SignupForm extends Component {
+ *   @expose @validate((rule) => rule.required().min(2).max(50)) name = "";
+ *   @expose @validate((rule) => rule.required().email()) email = "";
+ *   @expose @validate((rule) => rule.required().min(8).confirmed()) password = "";
+ * }
+ * ```
+ *
+ * @category Validation
+ */
+export function validate(
+  build: ValidateBuilder,
+): (value: unknown, context: ClassFieldDecoratorContext) => void {
+  return _fieldDecorator((proto, name) => _registerMap(_validateRules, proto, name, build));
+}
+
+// ── @on ───────────────────────────────────────────────────────────────────────
+
+/**
+ * Binds a method as a cross-component (realtime) event listener. Auto-exposes the method.
+ *
+ * @remarks
+ * When the named event is dispatched (via `dispatch` / `dispatchTo` / `dispatchSelf`, or an
+ * `echo:…` broadcast), the decorated method is invoked with the event payload. The event name
+ * autocompletes to the known {@link FlowEvents} contract while still accepting any string (for
+ * `echo:…` broadcasts and gradually-typed events). Annotate the handler's parameter with
+ * `EventPayload<"name">` to type the payload against the same contract. Because it auto-exposes,
+ * no separate `@expose` is needed. Applies to a method.
+ *
+ * @param eventName - The event to listen for; a known {@link FlowEvents} key or any string.
+ * @returns A method decorator that registers the listener.
+ *
+ * @example
+ * ```tsx
+ * class Feed extends Component {
+ *   @expose posts: Post[] = [];
+ *
+ *   @on("post-created")
+ *   onPostCreated(payload: EventPayload<"post-created">) {
+ *     this.posts = [payload, ...this.posts];
+ *   }
+ * }
+ * ```
+ *
+ * @category Realtime
+ */
+export function on(
+  eventName: LooseEventName,
+): (fn: unknown, context: ClassMethodDecoratorContext) => void {
+  return (_fn: unknown, context: ClassMethodDecoratorContext): void => {
+    context.addInitializer(function (this: unknown) {
+      const proto = Object.getPrototypeOf(this as object) as object;
+      const name = String(context.name);
+      _register(_exposedMethods, proto, name);
+      _registerMap(_onListeners, proto, eventName, name);
+    });
+  };
+}
+
+// ── @url ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Options for the {@link url} decorator, controlling how a property maps onto the browser URL
+ * query string.
+ *
+ * @category Persistence
+ */
+export interface UrlOptions {
+  /** Override the URL query parameter name. Defaults to the property name. */
+  as?: string;
+  /** Push a new history entry or replace the current one. Defaults to `'replace'`. */
+  history?: "push" | "replace";
+}
+
+type UrlDecorator = (value: unknown, context: ClassFieldDecoratorContext) => void;
+
+/**
+ * Syncs a field to the browser URL query string, so its value is reflected in and restored from
+ * the URL.
+ *
+ * @remarks
+ * Usable bare as `@url` (no parens) or configured as `@url({ as: 'page', history: 'push' })` — see
+ * {@link UrlOptions}. By default the query parameter takes the property's name and updates
+ * `replace` the current history entry.
+ *
+ * A URL-synced field is client-visible by definition, so `@url` **implies `@expose`** — no need
+ * to write both. Add `@locked` for a value the client reads but the server owns. Applies to a
+ * field.
+ *
+ * @param opts - Optional {@link UrlOptions} when called with parentheses.
+ * @returns When configured, a field decorator; when used bare, nothing (applied directly).
+ *
+ * @example
+ * ```tsx
+ * class ProductList extends Component {
+ *   @url page = 1;
+ *   @url({ as: "q", history: "push" }) search = "";
+ * }
+ * ```
+ *
+ * @category Persistence
+ */
+export function url(value: unknown, context: ClassFieldDecoratorContext): void;
+export function url(opts?: UrlOptions): UrlDecorator;
+export function url(
+  optsOrValue?: UrlOptions | unknown,
+  context?: ClassFieldDecoratorContext,
+): UrlDecorator | void {
+  if (context !== undefined) {
+    return _urlDecorator({})(optsOrValue, context); // bare @url
+  }
+  const opts = (optsOrValue ?? {}) as UrlOptions;
+  return _urlDecorator(opts);
+}
+
+function _urlDecorator(opts: UrlOptions): UrlDecorator {
+  return _fieldDecorator((proto, name) => {
+    _registerMap(_urlProps, proto, name, opts);
+    // A URL-synced field is client-visible by definition — its value is in the address bar,
+    // and keeping it in sync means the client holds it. So @url implies @expose; add @locked
+    // alongside it for a value the client reads but may not write.
+    _register(_exposedProps, proto, name);
+  });
+}
+
+// ── @param ────────────────────────────────────────────────────────────────────
+
+type ParamDecorator = (value: unknown, context: ClassFieldDecoratorContext) => void;
+
+/** A model class used as a `@param` token — matched against the resolved segment values. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any model constructor shape
+export type ParamModel = abstract new (...args: any[]) => unknown;
+
+/** Where a `@param` field reads from: a segment name, a model class, or its own name. */
+export type ParamSource = string | ParamModel | undefined;
+
+/** Fields bound to a route segment, with the source each one reads. */
+export function getRouteParamProps(instance: object): Map<string, ParamSource> {
+  _ensureDrained(instance);
+  return _collectMap(_routeParamProps, Object.getPrototypeOf(instance) as object);
+}
+
+/**
+ * Fills a field from the matched route segment before `onMount()` runs — including a
+ * [route-model binding](/docs/routing#route-model-binding), so a page on `/posts/:post`
+ * receives the loaded `Post` without querying for it.
+ *
+ * @remarks
+ * Usable bare as `@param` (the field's own name is the segment), as `@param('slug')` to read a
+ * differently-named segment, or as `@param(Post)` to take whichever segment resolved to an
+ * instance of that model — so the field never has to track what a route called it. One model
+ * claims one segment name, so the token form is unambiguous for anything binding implicitly;
+ * a route that hand-binds a second segment to the same model yields the leftmost.
+ *
+ * Seeding happens **once, on the initial GET** — the only request that carries the URL's
+ * segments. On subsequent WebSocket actions the value is restored from the snapshot instead
+ * (a model through Flow's model synth), so pair it with `@locked` and the record is never
+ * re-queried.
+ *
+ * `@param` registers the binding only; combine it with `@locked` for server-owned data, or
+ * `@expose` if the client may also write it. Applies to a field.
+ *
+ * @param name - The route segment to read; defaults to the property's own name.
+ * @returns When configured, a field decorator; when used bare, nothing (applied directly).
+ *
+ * @example
+ * ```tsx
+ * class PostDetailPage extends Component {
+ *   @locked @param post!: Post;           // /posts/:post -> the bound Post
+ *   @locked @param(Post) article!: Post;  // whichever segment resolved to a Post
+ *   @locked @param("tab") activeTab = ""; // /posts/:post/:tab -> the raw segment
+ * }
+ * ```
+ *
+ * @category Persistence
+ */
+export function param(value: unknown, context: ClassFieldDecoratorContext): void;
+export function param(source?: string | ParamModel): ParamDecorator;
+export function param(
+  sourceOrValue?: string | ParamModel | unknown,
+  context?: ClassFieldDecoratorContext,
+): ParamDecorator | void {
+  if (context !== undefined) {
+    return _paramDecorator(undefined)(sourceOrValue, context); // bare @param
+  }
+  return _paramDecorator(sourceOrValue as ParamSource);
+}
+
+function _paramDecorator(source: ParamSource): ParamDecorator {
+  return _fieldDecorator((proto, prop) => _registerMap(_routeParamProps, proto, prop, source));
+}
+
+// ── @session ──────────────────────────────────────────────────────────────────
+
+/** Options for {@link session}. */
+export interface SessionOptions {
+  /** Session key to read and write. Defaults to the property's own name. */
+  key?: string;
+  /**
+   * Namespace the key to this component (`flow:<Component>:<key>`), so the value belongs to
+   * this page alone and cannot collide with another component's field of the same name.
+   * Default: `false` — the key is the session's own.
+   */
+  scoped?: boolean;
+}
+
+type SessionDecorator = (value: unknown, context: ClassFieldDecoratorContext) => void;
+
+/**
+ * Binds a field to the server-side session, so its value survives across page loads.
+ *
+ * @remarks
+ * Requires `SessionMiddleware`. The field reads and writes the session's own key of the same
+ * name, so `@session userId` is the same `userId` a controller sees — pass `{ key }` to read a
+ * differently-named one, or `{ scoped: true }` to namespace it to this component instead.
+ *
+ * The value stays **server-side**: `@session` alone puts nothing in the snapshot, so the
+ * browser never sees it and cannot write it. Add `@locked` for a value the client should read.
+ * Applies to a field only.
+ *
+ * @param opts - Optional {@link SessionOptions} when called with parentheses.
+ * @returns When configured, a field decorator; when used bare, nothing (applied directly).
+ *
+ * @example
+ * ```tsx
+ * class Preferences extends Component {
+ *   @session userId = "";                          // the session's `userId`
+ *   @session({ key: "s" }) whatever = 0;           // the session's `s`
+ *   @session({ scoped: true }) draft = "";         // flow:Preferences:draft
+ *   @locked @session theme = "light";              // readable by the client, server-owned
+ * }
+ * ```
+ *
+ * @category Persistence
+ */
+export function session(value: unknown, context: ClassFieldDecoratorContext): void;
+export function session(opts?: SessionOptions): SessionDecorator;
+export function session(
+  optsOrValue?: SessionOptions | unknown,
+  context?: ClassFieldDecoratorContext,
+): SessionDecorator | void {
+  if (context !== undefined) {
+    return _sessionDecorator({})(optsOrValue, context); // bare @session
+  }
+  return _sessionDecorator((optsOrValue ?? {}) as SessionOptions);
+}
+
+function _sessionDecorator(opts: SessionOptions): SessionDecorator {
+  return _fieldDecorator((proto, name) => _registerMap(_sessionProps, proto, name, opts));
+}