@zerotal/flow 1.7.0 → 1.7.3

package/src/client/framePanes.ts

@@ -0,0 +1,229 @@
+/**
+ * What a time-travel frame opens into, as a small strip of its own tabs.
+ *
+ * The same shape a request uses in the devtools list, and for the same reason:
+ * the views are alternatives, not a sequence. You are reading the arguments the
+ * click sent, *or* the state it moved, *or* the SQL it ran on the server — and
+ * stacking them makes you scroll past two to reach the third.
+ *
+ * Only the views a frame actually has appear, so the strip doubles as the
+ * summary: a frame showing `Sent · State 2 · Server · Queries 3` has told you
+ * what the action did before you click anything.
+ *
+ * Pure string-building, with no `window` or `document` at module scope, so the
+ * decisions here are testable without a browser — which is the point, since the
+ * interesting cases (an action that queried, an action that only logged) depend
+ * on a signed-in session that is awkward to drive in a headless one.
+ */
+import type { TimelineFrame } from "./timeline.ts";
+
+/** What the server did while handling one action, read off its devtools trace. */
+export interface FrameServerCost {
+  durationMs: number;
+  ip: string | null;
+  statusCode: number | null;
+  queries: Array<{ sql: string; durationMs: number | null; rowCount: number | null }>;
+  logs: Array<{ level: string; text: string }>;
+  error: string | null;
+}
+
+/** One view of an action: a tab in the frame's own strip. */
+export interface FramePane {
+  id: string;
+  label: string;
+  /** Shown beside the label when the view counts something. */
+  count?: number;
+  html: string;
+}
+
+function esc(s: string): string {
+  return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** A value as the panes show it — compact JSON, truncated rather than wrapped. */
+export function brief(value: unknown, max = 160): string {
+  let text: string;
+  try {
+    text = typeof value === "string" ? value : JSON.stringify(value);
+  } catch {
+    text = String(value);
+  }
+  if (text === undefined || text === null) text = String(value);
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * The value out of a snapshot entry, which is stored as `[value, meta]`.
+ *
+ * A developer reading a state diff wants `1 → 2`, not `[1,{}] → [2,{}]`: the
+ * second slot is the framework's own bookkeeping and only earns space when it
+ * holds something.
+ */
+export function snapshotValue(entry: unknown): unknown {
+  if (!Array.isArray(entry) || entry.length === 0) return entry;
+  const [value, meta] = entry as [unknown, unknown];
+  const bare =
+    meta === undefined || meta === null || (isPlainObject(meta) && !Object.keys(meta).length);
+  return bare ? value : { value, meta };
+}
+
+/** One `key  before → after` row per field the action changed. */
+function stateHtml(frame: TimelineFrame, frames: readonly TimelineFrame[]): string {
+  if (!frame.changed.length) return "";
+  const prior = frames.filter((f) => f.compId === frame.compId && f.seq < frame.seq).pop();
+  const before = prior?.snapshot?.data as Record<string, unknown> | undefined;
+  const after = frame.snapshot?.data as Record<string, unknown> | undefined;
+
+  return frame.changed
+    .map((key) => {
+      const from = before && key in before ? brief(snapshotValue(before[key]), 60) : "—";
+      const to = after && key in after ? brief(snapshotValue(after[key]), 60) : "—";
+      return (
+        `<div style="display:flex;gap:8px;align-items:baseline;padding:1px 0">` +
+        `<span style="min-width:120px;color:var(--cyan)">${esc(key)}</span>` +
+        `<span class="dim">${esc(from)}</span>` +
+        `<span class="dim">→</span>` +
+        `<span style="color:var(--green)">${esc(to)}</span>` +
+        `</div>`
+      );
+    })
+    .join("");
+}
+
+/** The call the browser made: its arguments, and any client writes flushed with it. */
+function sentHtml(frame: TimelineFrame): string {
+  if (!frame.sent) return "";
+  const args = frame.sent.args.length
+    ? frame.sent.args.map((a) => brief(a, 80)).join(", ")
+    : "no arguments";
+  const updates = frame.sent.updates ? Object.entries(frame.sent.updates) : [];
+  const updateRows = updates
+    .map(
+      ([k, v]) =>
+        `<div style="display:flex;gap:8px;padding:1px 0">` +
+        `<span style="min-width:120px;color:var(--cyan)">${esc(k)}</span>` +
+        `<span class="dim">${esc(brief(v, 60))}</span></div>`,
+    )
+    .join("");
+  return (
+    `<div><span style="color:var(--purple)">${esc(frame.action)}</span>` +
+    `<span class="dim">(${esc(args)})</span></div>` +
+    (updateRows
+      ? `<div class="dim" style="font-size:10px;margin:4px 0 1px">flushed with the call</div>${updateRows}`
+      : "")
+  );
+}
+
+function serverHtml(s: FrameServerCost): string {
+  return (
+    `<div style="display:flex;gap:10px;flex-wrap:wrap">` +
+    `<span class="dim">${s.durationMs}ms</span>` +
+    (s.statusCode ? `<span class="dim">status ${s.statusCode}</span>` : "") +
+    (s.ip ? `<span class="dim">from ${esc(s.ip)}</span>` : "") +
+    `</div>` +
+    (s.error ? `<div class="red" style="margin-top:2px">${esc(s.error)}</div>` : "")
+  );
+}
+
+function queriesHtml(s: FrameServerCost): string {
+  return s.queries
+    .map(
+      (q) =>
+        `<div style="display:flex;gap:8px;align-items:baseline;padding:1px 0">` +
+        `<span style="flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap">${esc(brief(q.sql, 140))}</span>` +
+        `<span class="dim" style="font-size:10px">${q.durationMs ?? "—"}ms` +
+        `${q.rowCount === null ? "" : ` · ${q.rowCount} row${q.rowCount === 1 ? "" : "s"}`}</span>` +
+        `</div>`,
+    )
+    .join("");
+}
+
+function logsHtml(s: FrameServerCost): string {
+  return s.logs
+    .map(
+      (l) =>
+        `<div style="padding:1px 0">` +
+        `<span class="dim" style="min-width:44px;display:inline-block">${esc(l.level)}</span>` +
+        `${esc(brief(l.text, 140))}</div>`,
+    )
+    .join("");
+}
+
+/**
+ * The views a frame has to offer, in reading order.
+ *
+ * `cost` is null for a frame that never left the browser — a client expression —
+ * and that frame says so rather than showing an empty Server pane.
+ */
+export function framePanes(
+  frame: TimelineFrame,
+  frames: readonly TimelineFrame[],
+  cost: FrameServerCost | null,
+): FramePane[] {
+  const panes: FramePane[] = [];
+
+  const sent = sentHtml(frame);
+  if (sent) panes.push({ id: "sent", label: "Sent", html: sent });
+
+  const state = stateHtml(frame, frames);
+  if (state) panes.push({ id: "state", label: "State", count: frame.changed.length, html: state });
+
+  if (!cost) {
+    panes.push({
+      id: "server",
+      label: "Server",
+      html: `<div class="dim" style="font-size:11px">Ran in the browser — nothing was sent to the server.</div>`,
+    });
+    return panes;
+  }
+
+  panes.push({ id: "server", label: "Server", html: serverHtml(cost) });
+  if (cost.queries.length) {
+    panes.push({
+      id: "queries",
+      label: "Queries",
+      count: cost.queries.length,
+      html: queriesHtml(cost),
+    });
+  }
+  if (cost.logs.length) {
+    panes.push({ id: "logs", label: "Logs", count: cost.logs.length, html: logsHtml(cost) });
+  }
+  return panes;
+}
+
+/**
+ * Which pane is showing, given what the reader last picked.
+ *
+ * One preference across every frame rather than one each: stepping down a list of
+ * actions comparing the SQL of one against the next should keep showing SQL, not
+ * return you to the arguments at each step. Falls back to the first pane the
+ * frame in hand actually has.
+ */
+export function activePane(preferred: string, panes: FramePane[]): string {
+  return panes.some((p) => p.id === preferred) ? preferred : (panes[0]?.id ?? "");
+}
+
+/** A frame's panes, as the strip plus the one body that is showing. */
+export function renderFramePanes(panes: FramePane[], preferred: string): string {
+  if (!panes.length) return "";
+  const active = activePane(preferred, panes);
+  const strip = panes
+    .map(
+      (p) =>
+        `<button class="dsect${p.id === active ? " on" : ""}" data-fsec="${p.id}">` +
+        `${esc(p.label)}` +
+        (p.count === undefined ? "" : `<span class="dsec-n">${p.count}</span>`) +
+        `</button>`,
+    )
+    .join("");
+  const body = panes.find((p) => p.id === active)?.html ?? "";
+  return (
+    `<div class="dsecs">${strip}</div>` +
+    `<div class="dsec-body" style="padding:6px 12px">${body}</div>`
+  );
+}

package/src/client/headless.ts

@@ -523,7 +523,13 @@ export function flowFileUpload(config: { name: string }) {
         this.error = e.detail.error ?? "Upload failed";
       }) as EventListener);
 
-      on("flow:upload-done", ((e: CustomEvent) => {
+      // `-finish`, not `-done`. The bridge dispatches `flow:upload-finish`
+      // (`_uploadFiles`) and the guide documents that name; this listener was the
+      // only place `flow:upload-done` appeared, and nothing has ever dispatched
+      // it. So the success path never ran: `uploading` stayed true after a
+      // perfectly good upload and the dropzone read "Uploading… 100%" forever,
+      // while the file itself had already been stored and bound.
+      on("flow:upload-finish", ((e: CustomEvent) => {
         if (e.detail.key !== this.name) return;
         this.uploading = false;
         this.progress = 100;

package/src/client/timeline.ts

@@ -27,6 +27,16 @@ export interface TimelineFrame {
   /** The component's outer HTML at this frame, for DOM restore on a jump. */
   html: string | null;
   ts: number;
+  /**
+   * What the browser sent to produce this frame — absent for a mount, and for a
+   * frame produced by anything other than a dispatched action.
+   *
+   * Kept so the panel can answer "what did this click actually send" without the
+   * developer reading the socket. `updates` is the batch of client-side writes
+   * flushed alongside the call, which is why a field can differ between frames
+   * without appearing in `args`.
+   */
+  sent?: { args: unknown[]; updates?: Record<string, unknown> };
 }
 
 const MAX_FRAMES = 250;
@@ -87,6 +97,7 @@ export function recordFrame(input: {
   action: string;
   snapshot: Snapshot;
   html: string | null;
+  sent?: { args: unknown[]; updates?: Record<string, unknown> };
 }): TimelineFrame | null {
   if (!_enabled) return null;
   const changed = computeChanged(_lastDataByComp.get(input.compId), input.snapshot.data);
@@ -100,6 +111,7 @@ export function recordFrame(input: {
     changed,
     html: input.html,
     ts: Date.now(),
+    ...(input.sent ? { sent: input.sent } : {}),
   };
   _frames.push(frame);
   if (_frames.length > MAX_FRAMES) _frames.shift();

package/src/components.ts

@@ -28,6 +28,15 @@ import { jsLiteral } from "./utils.ts";
 export interface LinkProps {
   href: string;
   hover?: boolean;
+  /**
+   * Prefetch on pointer-down instead of on hover.
+   *
+   * The right choice for a row in a long list: hover prefetch fires for every
+   * link the pointer crosses on its way somewhere else, which on a dense table
+   * is a fetch per row nobody chose. Pointer-down fires once, on the one link
+   * the reader has committed to, and still lands ahead of the click.
+   */
+  down?: boolean;
   current?: boolean;
   exact?: boolean;
   preserveScroll?: boolean;
@@ -39,7 +48,8 @@ export interface LinkProps {
  * that you can override or refine per link.
  *
  * @remarks
- * `hover` prefetches the target on hover; `current` forces (`true`) or suppresses
+ * `hover` prefetches the target on hover and `down` on pointer-down (the one to reach
+ * for inside a long list); `current` forces (`true`) or suppresses
  * (`false`) the active state instead of deriving it from the URL; `exact` restricts
  * the automatic active state to an exact path match. Any other props pass through to
  * the `<a>`.
@@ -60,9 +70,10 @@ export interface LinkProps {
  * @category Navigation & data
  */
 export function Link(props: LinkProps & { children?: unknown }): HtmlNode {
-  const { href, hover, current, exact, preserveScroll, children, ...rest } = props;
+  const { href, hover, down, current, exact, preserveScroll, children, ...rest } = props;
   const out: Record<string, unknown> = { ...rest, href, navigate: true, children };
   if (hover) out["navigateHover"] = true;
+  if (down) out["navigateDown"] = true;
   if (preserveScroll) out["navigatePreserveScroll"] = true;
   // `current` overrides the automatic URL-based active state:
   //   false → never active (flow:current.ignore)

package/src/decorators.ts

@@ -52,7 +52,7 @@ 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 _onListeners = new WeakMap<object, Map<ListenerName, string>>();
 const _urlProps = new WeakMap<object, Map<string, UrlOptions>>();
 /**
  * prop -> where its value comes from:
@@ -77,10 +77,10 @@ function _register(map: WeakMap<object, Set<string>>, proto: object, key: string
   s.add(key);
 }
 
-function _registerMap<V>(
-  map: WeakMap<object, Map<string, V>>,
+function _registerMap<V, K = string>(
+  map: WeakMap<object, Map<K, V>>,
   proto: object,
-  key: string,
+  key: K,
   value: V,
 ): void {
   let m = map.get(proto);
@@ -102,8 +102,11 @@ function _collect(map: WeakMap<object, Set<string>>, startProto: object): Set<st
   return result;
 }
 
-function _collectMap<V>(map: WeakMap<object, Map<string, V>>, startProto: object): Map<string, V> {
-  const result = new Map<string, V>();
+function _collectMap<V, K = string>(
+  map: WeakMap<object, Map<K, V>>,
+  startProto: object,
+): Map<K, V> {
+  const result = new Map<K, V>();
   let proto: object | null = startProto;
   while (proto && proto !== Object.prototype) {
     const m = map.get(proto);
@@ -131,7 +134,8 @@ interface MemberTag {
   renderless?: boolean;
   task?: boolean;
   computed?: boolean;
-  on?: string;
+  /** The event name, or a resolver over the instance — see {@link ListenerName}. */
+  on?: ListenerName;
 }
 
 // `unique symbol` (not a plain `symbol`) so the computed-key types below resolve.
@@ -302,11 +306,34 @@ function _drainFields(ctor: unknown): void {
   // recently enqueued group: a class is drained after its own definition, so among
   // equal candidates the newest is the one that just defined it, and older equals are
   // leftovers by construction.
+  //
+  // Restricted first to groups this class could plausibly own: every name in the
+  // group is a field this class DECLARES. A sibling's group is rejected by the
+  // names it has that this class does not.
+  //
+  // Length alone was not enough to separate siblings of one decorated base. Given
+  // `NewPage { project }` and `EditPage { project, issue }` over a shared base, a
+  // drain of NewPage scanned every group, found `project` at the head of EditPage's
+  // group, tied on length with its own single entry, and — ties going to the newest
+  // group — claimed EditPage's `project` and spliced it away. EditPage then drained
+  // to `issue` alone, its `project` never registered, and route-param seeding skipped
+  // the field: a 500 on `this.project.slug` that appeared only when the sibling
+  // rendered first. Containment separates them, because `issue` is not a field
+  // NewPage declares.
+  //
+  // Falls back to every group when nothing is fully contained, so partial matches —
+  // including entries buffered without metadata, which share one bucket — behave as
+  // they did.
+  const contained = groups.filter((key) =>
+    byGroup.get(key)!.every((i) => ownIndex.has(_pendingFields[i]!.name)),
+  );
+  const candidates = contained.length > 0 ? contained : groups;
+
   let bestIdxs: number[] | null = null;
   let bestLen = 0;
   let bestGroup = -1;
-  for (let g = 0; g < groups.length; g++) {
-    const idxs = byGroup.get(groups[g]!)!;
+  for (let g = 0; g < candidates.length; g++) {
+    const idxs = byGroup.get(candidates[g]!)!;
 
     // Longest contiguous run whose names map to strictly-increasing declaration-order
     // indices (equal allowed only for an identical repeated name — multiple decorators
@@ -433,9 +460,9 @@ 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> {
+export function getListeners(PageClass: { prototype: object }): Map<ListenerName, string> {
   _scanChain(PageClass.prototype as object);
-  return _collectMap(_onListeners, PageClass.prototype as object);
+  return _collectMap<string, ListenerName>(_onListeners, PageClass.prototype as object);
 }
 export function getUrlProps(instance: object): Map<string, UrlOptions> {
   _ensureDrained(instance);
@@ -923,14 +950,36 @@ export function validate(
 
 // ── @on ───────────────────────────────────────────────────────────────────────
 
+/**
+ * What a `@on` listener listens to: a static event name, or a resolver called with the component
+ * instance to compute one — the same shape as {@link PresenceChannel} and {@link SharedChannel}.
+ *
+ * Use the resolver form for a `socket:` channel whose name contains a value only the instance
+ * knows. A template literal in a plain string cannot work: the decorator's argument is read off
+ * the class, long before any instance exists, so `"socket:issues.${this.id},E"` subscribes to a
+ * channel whose name contains those eleven characters.
+ *
+ * @example
+ * ```ts
+ * // Static — the channel is the same for every instance.
+ * @on("socket:orders,OrderPlaced")
+ *
+ * // Per-instance — one channel per issue.
+ * @on((self) => `socket-private:issues.${self.issue.id},CommentPosted`)
+ * ```
+ *
+ * @category Realtime
+ */
+export type ListenerName = LooseEventName | ((self: Record<string, any>) => string); // eslint-disable-line @typescript-eslint/no-explicit-any -- `unknown` would break `self.issue.id`
+
 /**
  * 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
+ * `socket:…` 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
+ * `socket:…` 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.
  *
@@ -952,7 +1001,7 @@ export function validate(
  * @category Realtime
  */
 export function on(
-  eventName: LooseEventName,
+  eventName: ListenerName,
 ): (fn: unknown, context: ClassMethodDecoratorContext) => void {
   return (_fn: unknown, context: ClassMethodDecoratorContext): void => {
     // `@on` implies `@expose`; the tag carries the event name so the scan can rebuild the map.
@@ -966,6 +1015,47 @@ export function on(
   };
 }
 
+/**
+ * The listener names a component actually subscribes to, resolved against `instance`.
+ *
+ * A static name passes through; a resolver is called with the component, so an
+ * `socket:` channel can carry a value only the instance knows — `issues.417` rather
+ * than the class-level `issues.:id`.
+ *
+ * This exists because the channel name reaches the browser through the snapshot,
+ * and the snapshot is built per instance. Registering `(self) => …` under the
+ * *class* and resolving here is the same split {@link presence} and {@link shared}
+ * already use; before it, a `@on("socket-private:issues.${this.issueId},…")`
+ * written the way the guide showed subscribed to a channel literally containing
+ * `${this.issueId}` — no error, no warning, and no events, because template
+ * syntax inside a plain string is just text.
+ *
+ * A resolver that throws is dropped rather than allowed to fail the render: a
+ * page whose live updates do not arrive is a degraded page, while a page that
+ * 500s because one channel could not be named is no page at all.
+ */
+export function resolveListeners(
+  listeners: Map<ListenerName, string>,
+  instance: object,
+): Map<string, string> {
+  const resolved = new Map<string, string>();
+
+  for (const [name, method] of listeners) {
+    if (typeof name !== "function") {
+      resolved.set(name, method);
+      continue;
+    }
+    try {
+      const channel = name(instance as Record<string, unknown>);
+      if (typeof channel === "string" && channel !== "") resolved.set(channel, method);
+    } catch {
+      /* an unresolvable channel is not subscribed to */
+    }
+  }
+
+  return resolved;
+}
+
 // ── @url ──────────────────────────────────────────────────────────────────────
 
 /**

package/src/dehydrate.ts

@@ -8,6 +8,7 @@ import {
   getLockedProps,
   getUrlProps,
   getListeners,
+  resolveListeners,
   getPresenceProps,
   resolvePresenceChannel,
   getSharedProps,
@@ -124,9 +125,14 @@ export function dehydrate(
     data[key] = [serialized, meta];
   }
 
-  // Collect @on listeners for the client event router.
+  // Collect @on listeners for the client event router, resolving any registered as
+  // `(self) => name` against this instance — that is what lets a `socket:` channel carry
+  // a per-record id, since the decorator's argument is read off the class.
   // Excluded from HMAC signing (server-derived, can't usefully be tampered with).
-  const listenersMap = getListeners(page.constructor as { prototype: object });
+  const listenersMap = resolveListeners(
+    getListeners(page.constructor as { prototype: object }),
+    page,
+  );
   const listeners = listenersMap.size > 0 ? Object.fromEntries(listenersMap) : undefined;
 
   // Named slot HTML passed down by the parent. Signed (server-generated), and carried
@@ -216,6 +222,49 @@ export async function hydrate<T extends Component>(
   return page;
 }
 
+/**
+ * A copy of `snapshot` with client-supplied hidden values removed, re-signed.
+ *
+ * A hidden field the user typed — a new password — rides in the snapshot so it survives until
+ * they save. That is fine on the wire, where it goes back to the browser that produced it,
+ * and wrong in the durable store, which writes the whole snapshot server-side after every
+ * request and may be backed by Redis. A half-typed password should not be waiting there for
+ * anyone, and resuming into one is not what durable is for.
+ *
+ * Re-signed rather than edited in place: the checksum covers `data`, so a strip without a
+ * fresh signature would produce a snapshot that fails its own verification on restore.
+ *
+ * @internal
+ */
+export function stripPendingSecrets(snapshot: Snapshot): Snapshot {
+  let touched = false;
+  const data: SnapshotData = {};
+
+  for (const [prop, [value, meta]] of Object.entries(snapshot.data)) {
+    const pending = meta["p"];
+    if (
+      !Array.isArray(pending) ||
+      pending.length === 0 ||
+      value === null ||
+      typeof value !== "object"
+    ) {
+      data[prop] = [value, meta];
+      continue;
+    }
+    touched = true;
+    const cleanValue: Record<string, unknown> = { ...(value as Record<string, unknown>) };
+    for (const key of pending as string[]) delete cleanValue[key];
+    const cleanMeta = { ...meta };
+    delete cleanMeta["p"];
+    data[prop] = [cleanValue, cleanMeta];
+  }
+
+  if (!touched) return snapshot;
+
+  const stripped = { ...snapshot, data };
+  return { ...stripped, checksum: _sign(_signingPayload(stripped)) };
+}
+
 /** Verify a snapshot's HMAC against the current APP_KEY. Public so durable-snapshot
  *  restore can validate a stored snapshot before trusting it (a rotated key → false). */
 export function verifySnapshot(snapshot: Snapshot): boolean {

package/src/durable.ts

@@ -13,7 +13,7 @@
 import type { Component } from "./Component.ts";
 import type { Snapshot } from "./types.ts";
 import type { HttpContext } from "@zerotal/core";
-import { verifySnapshot, applySnapshotData } from "./dehydrate.ts";
+import { verifySnapshot, applySnapshotData, stripPendingSecrets } from "./dehydrate.ts";
 
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
 
@@ -221,7 +221,10 @@ export async function persistDurable(
     await _store.delete(key);
     return;
   }
-  await _store.set(key, snapshot, cfg.ttlMs);
+  // Never persist a hidden field the client is part-way through typing — see
+  // `stripPendingSecrets`. The wire may carry it back to the browser that produced it; a
+  // server-side store, possibly Redis, may not hold it.
+  await _store.set(key, stripPendingSecrets(snapshot), cfg.ttlMs);
 }
 
 /**

package/src/events.ts

@@ -13,7 +13,7 @@
 //     }
 //   }
 //
-// Unknown event names still work (a `string` fallback overload keeps `echo:…` broadcasts and
+// Unknown event names still work (a `string` fallback overload keeps `socket:…` broadcasts and
 // gradual adoption compiling), they're just untyped. Payloads are object shapes or `void`.
 
 /**
@@ -24,7 +24,7 @@
  *
  * @remarks
  * Payloads are object shapes or `void` (for events with no payload). Unknown event names still
- * compile (a `string` fallback keeps `echo:…` broadcasts and gradual adoption working); they are
+ * compile (a `string` fallback keeps `socket:…` broadcasts and gradual adoption working); they are
  * simply untyped.
  *
  * @example
@@ -64,7 +64,7 @@ export type EventPayload<K extends EventName> = FlowEvents[K];
  */
 export type EventArgs<P> = [P] extends [void] ? [] : [payload: P];
 
-/** An event name loosened to accept any string (autocomplete for known names, `echo:…` too). */
+/** An event name loosened to accept any string (autocomplete for known names, `socket:…` too). */
 export type LooseEventName = EventName | (string & {});
 
 // ── Optional runtime shape guards ──────────────────────────────────────────────

package/src/index.ts

@@ -189,6 +189,7 @@ export { renderless } from "./decorators.ts";
 export { task } from "./decorators.ts";
 export { validate } from "./decorators.ts";
 export { on } from "./decorators.ts";
+export type { ListenerName } from "./decorators.ts";
 export { url } from "./decorators.ts";
 export { param } from "./decorators.ts";
 export { session } from "./decorators.ts";

package/src/jsx-runtime.ts

@@ -59,6 +59,7 @@ interface FlowDirectives {
 
   navigate?: boolean;
   navigateHover?: boolean;
+  navigateDown?: boolean;
   navigatePreserveScroll?: boolean;
   current?: string;
   currentExact?: boolean;
@@ -147,9 +148,20 @@ interface FlowDirectives {
   show?: any;
   showImportant?: boolean;
 
+  /**
+   * The reorder action, as a method reference or its name.
+   *
+   * Read off the container a child was **dropped into** and called `(key, index)`,
+   * so the destination is encoded in which method runs and nowhere in the payload.
+   * Dragging between containers therefore needs one action per container.
+   */
   onSort?: any;
   sortItem?: any;
   sortGroup?: string;
+  /**
+   * Emitted as `flow:sort:group-id`, and **currently read by nothing** — neither the
+   * client runtime nor the compiler looks for it. Setting it has no effect today.
+   */
   sortGroupId?: any;
   sortHandle?: boolean;
   sortIgnore?: boolean;
@@ -738,6 +750,7 @@ const PULSE_PROP_MAP: Record<string, string> = {
   dirtyTarget: "flow:target",
   navigate: "flow:navigate",
   navigateHover: "flow:navigate.hover",
+  navigateDown: "flow:navigate.down",
   // One word on purpose: toFlowHtmlAttr() rewrites every `-` in a flow: attribute
   // to a `.`, so a hyphenated modifier would reach the DOM under a different name
   // here than the compiler emits.