@orieljs/live 0.1.0-alpha.4 → 0.1.0-alpha.6

package/dist/index.js

@@ -2,6 +2,50 @@
 import { LiveManager, UrlGenerator, ValidationFactory } from "@orieljs/contracts";
 import { inject } from "@orieljs/container";
 
+// errors.ts
+var LiveError = class extends Error {
+  name = "LiveError";
+  kind = "Server";
+  status = 500;
+};
+var CorruptComponentPayloadError = class extends LiveError {
+  name = "CorruptComponentPayloadError";
+  kind = "Authorization";
+  status = 403;
+  constructor(component = "unknown") {
+    super(`Live encountered corrupt data when trying to hydrate the [${component}] component.`);
+  }
+};
+var MethodNotCallableError = class extends LiveError {
+  name = "MethodNotCallableError";
+  kind = "Authorization";
+  status = 403;
+  constructor(method, component) {
+    super(`Unable to call component method. Public method [${method}] not found on component [${component}].`);
+  }
+};
+var PropertyNotUpdatableError = class extends LiveError {
+  name = "PropertyNotUpdatableError";
+  kind = "Authorization";
+  status = 403;
+  constructor(path, component) {
+    super(`Cannot update property [${path}] on component [${component}]: it is not a public, unlocked property.`);
+  }
+};
+var LiveComponentNotFoundError = class extends LiveError {
+  name = "LiveComponentNotFoundError";
+  kind = "Http";
+  status = 404;
+  constructor(component) {
+    super(`Unable to find component: [${component}].`);
+  }
+};
+var InvalidLiveRequestError = class extends LiveError {
+  name = "InvalidLiveRequestError";
+  kind = "Http";
+  status = 400;
+};
+
 // metadata.ts
 Symbol.metadata ??= /* @__PURE__ */ Symbol.for("Symbol.metadata");
 var LISTENERS = /* @__PURE__ */ Symbol.for("oriel:live.listeners");
@@ -75,6 +119,153 @@ function computedOf(cls) {
   return /* @__PURE__ */ new Set([...metadataOf(cls)[COMPUTED] ?? [], ...staticsOf(cls, "computed").flat()]);
 }
 
+// security.ts
+import { Collection as Collection2 } from "@orieljs/collections";
+
+// synthesizers.ts
+import { Collection } from "@orieljs/collections";
+function isModel(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value;
+  return typeof candidate.getKey === "function" && typeof candidate.getKeyName === "function" && typeof candidate.getTable === "function" && typeof candidate.exists === "boolean";
+}
+var isPlainObject = (value) => {
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+};
+var isTuple = (value) => Array.isArray(value) && value.length === 2 && typeof value[1] === "object" && value[1] !== null && !Array.isArray(value[1]) && typeof value[1].s === "string";
+function classNameOf(registry, cls) {
+  return registry.nameOf(cls) ?? registry.register(cls);
+}
+function dehydrate(value, registry, path, seen = /* @__PURE__ */ new Set()) {
+  switch (typeof value) {
+    case "undefined":
+      return [null, { s: "u" }];
+    case "string":
+    case "boolean":
+      return value;
+    case "number":
+      if (!Number.isFinite(value)) throw new LiveError(`Property [${path}] is ${value}: Live state must be JSON (finite numbers only).`);
+      return value;
+    case "bigint":
+    case "symbol":
+    case "function":
+      throw new LiveError(`Property [${path}] holds a ${typeof value}: Live state may only hold primitives, arrays, plain objects, Dates, models and collections.`);
+  }
+  if (value === null) return null;
+  const object = value;
+  if (seen.has(object)) throw new LiveError(`Property [${path}] contains a circular reference.`);
+  seen.add(object);
+  try {
+    if (object instanceof Date) return [object.toISOString(), { s: "dt" }];
+    if (Array.isArray(object)) return [object.map((item, i) => dehydrate(item, registry, `${path}.${i}`, seen)), { s: "arr" }];
+    if (isModel(object)) {
+      const name = classNameOf(registry, object.constructor);
+      if (!object.exists) throw new LiveError(`Property [${path}] holds an unsaved [${name}] model: only saved models can be kept between requests.`);
+      return [null, { s: "mdl", class: name, key: object.getKey() }];
+    }
+    if (object instanceof Collection) {
+      const items = object.all();
+      const first = items[0];
+      if (items.length > 0 && isModel(first) && items.every((item) => isModel(item) && item.constructor === first.constructor)) {
+        for (const [i, item] of items.entries()) {
+          if (!item.exists) throw new LiveError(`Property [${path}.${i}] holds an unsaved model.`);
+        }
+        const name = classNameOf(registry, first.constructor);
+        return [null, { s: "elcln", class: name, keys: items.map((item) => item.getKey()) }];
+      }
+      return [items.map((item, i) => dehydrate(item, registry, `${path}.${i}`, seen)), { s: "clctn" }];
+    }
+    if (isPlainObject(object)) {
+      const out = {};
+      for (const [key, item] of Object.entries(object)) out[key] = dehydrate(item, registry, `${path}.${key}`, seen);
+      return [out, { s: "obj" }];
+    }
+    const type = object.constructor?.name || "object";
+    throw new LiveError(
+      `Property [${path}] holds a [${type}] instance: Live state may only hold primitives, arrays, plain objects, Dates, models and collections.`
+    );
+  } finally {
+    seen.delete(object);
+  }
+}
+function modelClass(registry, name) {
+  if (typeof name !== "string" || !registry.has(name)) throw new LiveError(`Unable to hydrate the [${String(name)}] model: it is not registered.`);
+  return registry.resolve(name);
+}
+async function hydrate(value, registry) {
+  if (!isTuple(value)) return value;
+  const [inner, meta] = value;
+  switch (meta.s) {
+    case "u":
+      return void 0;
+    case "dt":
+      return new Date(String(inner));
+    case "arr":
+      return Promise.all(inner.map((item) => hydrate(item, registry)));
+    case "clctn":
+      return new Collection(await Promise.all(inner.map((item) => hydrate(item, registry))));
+    case "obj": {
+      const out = {};
+      for (const [key, item] of Object.entries(inner)) {
+        Object.defineProperty(out, key, { value: await hydrate(item, registry), enumerable: true, writable: true, configurable: true });
+      }
+      return out;
+    }
+    case "mdl":
+      return modelClass(registry, meta.class).findOrFail(meta.key);
+    case "elcln": {
+      const cls = modelClass(registry, meta.class);
+      const keys = meta.keys ?? [];
+      const keyName = new cls().getKeyName();
+      const found = [...await cls.query().whereIn(keyName, keys).get()];
+      const byKey = new Map(found.map((model) => [String(model.getKey()), model]));
+      return new Collection(keys.map((key) => byKey.get(String(key))).filter((model) => model !== void 0));
+    }
+  }
+  throw new LiveError(`Unknown snapshot value type [${String(meta.s)}].`);
+}
+
+// security.ts
+var HOOKS = /* @__PURE__ */ new Set(["constructor", "render", "mount", "boot", "booted", "hydrate", "dehydrate", "updating", "updated", "rendering", "rendered", "exception"]);
+var HOOK_PREFIX = /^(updating|updated|hydrate|dehydrate)[A-Z_]/;
+var UNSAFE_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
+var baseApi;
+var isBaseApi = (name) => (baseApi ??= new Set(Object.getOwnPropertyNames(Component.prototype))).has(name);
+var INDEX = /^(?:0|[1-9]\d*)$/;
+function isArraySlot(array, segment) {
+  return INDEX.test(segment) && Number(segment) <= array.length;
+}
+function isCallable(instance, method) {
+  if (method === "" || method.startsWith("_") || method.startsWith("$") || method.startsWith("#")) return false;
+  if (HOOKS.has(method) || HOOK_PREFIX.test(method) || isBaseApi(method)) return false;
+  if (lockedOf(instance.constructor).has(method)) return false;
+  const isBase = (proto) => proto === Component.prototype || proto === Object.prototype;
+  for (let proto = Object.getPrototypeOf(instance); proto !== null && !isBase(proto); proto = Object.getPrototypeOf(proto)) {
+    const descriptor = Object.getOwnPropertyDescriptor(proto, method);
+    if (descriptor !== void 0) return typeof descriptor.value === "function";
+  }
+  return false;
+}
+function isUpdatable(instance, path) {
+  const segments = path.split(".");
+  const root = segments[0];
+  if (root === "" || root.startsWith("_") || segments.some((segment) => segment === "" || UNSAFE_SEGMENTS.has(segment))) return false;
+  if (!Object.hasOwn(instance, root)) return false;
+  const descriptor = Object.getOwnPropertyDescriptor(instance, root);
+  if (!descriptor.enumerable || descriptor.get !== void 0) return false;
+  const cls = instance.constructor;
+  if (lockedOf(cls).has(root) || computedOf(cls).has(root)) return false;
+  let node = descriptor.value;
+  for (const segment of segments.slice(1)) {
+    if (isModel(node) || node instanceof Collection2) return false;
+    if (Array.isArray(node) && !isArraySlot(node, segment)) return false;
+    if (typeof node !== "object" || node === null || !Object.hasOwn(node, segment)) return true;
+    node = node[segment];
+  }
+  return !isModel(node) && !(node instanceof Collection2);
+}
+
 // Component.ts
 var COMPONENT = /* @__PURE__ */ Symbol.for("oriel:live.component");
 var states = /* @__PURE__ */ new WeakMap();
@@ -206,6 +397,23 @@ var Component = class {
   skipRender() {
     stateOf(this).skipRender = true;
   }
+  /**
+   * An action for an `o:` directive, typed against its method: `o:click={this.$action(this.delete, tag.id)}` writes
+   * `delete(5)`, and a string where `delete` takes a number is a type error. The arguments are written as JSON, the
+   * trailing `undefined` ones left out so the method's defaults apply. The method must be one of this component's
+   * actions (a public method of its class, not a hook and not @Locked); anything else throws while rendering.
+   */
+  $action(method, ...params) {
+    const name = typeof method === "function" ? method.name : "";
+    if (name === "" || this[name] !== method || !isCallable(this, name)) {
+      throw new LiveError(
+        `[${name === "" ? "anonymous function" : name}] is not an action of [${this.getName() || this.constructor.name}]: pass one of its public methods, as in this.$action(this.save).`
+      );
+    }
+    let count = params.length;
+    while (count > 0 && params[count - 1] === void 0) count--;
+    return count === 0 ? name : `${name}(${params.slice(0, count).map((param) => JSON.stringify(param) ?? "null").join(", ")})`;
+  }
   /** A full-page component as a route action: Route.get('/counter', Counter). Route parameters go to mount(). */
   async __invoke() {
     return inject(LiveManager).page(this);
@@ -219,58 +427,33 @@ import { inject as inject3 } from "@orieljs/container";
 // Testable.ts
 import { AssertionError } from "assert";
 import { isDeepStrictEqual } from "util";
-import { LiveManager as LiveManager2, token } from "@orieljs/contracts";
+import { LiveManager as LiveManager2, Session, token } from "@orieljs/contracts";
 import { Container, currentContainer, inject as inject2 } from "@orieljs/container";
 
-// errors.ts
-var LiveError = class extends Error {
-  name = "LiveError";
-  kind = "Server";
-  status = 500;
-};
-var CorruptComponentPayloadError = class extends LiveError {
-  name = "CorruptComponentPayloadError";
-  kind = "Authorization";
-  status = 403;
-  constructor(component = "unknown") {
-    super(`Live encountered corrupt data when trying to hydrate the [${component}] component.`);
-  }
-};
-var MethodNotCallableError = class extends LiveError {
-  name = "MethodNotCallableError";
-  kind = "Authorization";
-  status = 403;
-  constructor(method, component) {
-    super(`Unable to call component method. Public method [${method}] not found on component [${component}].`);
-  }
-};
-var PropertyNotUpdatableError = class extends LiveError {
-  name = "PropertyNotUpdatableError";
-  kind = "Authorization";
-  status = 403;
-  constructor(path, component) {
-    super(`Cannot update property [${path}] on component [${component}]: it is not a public, unlocked property.`);
-  }
-};
-var LiveComponentNotFoundError = class extends LiveError {
-  name = "LiveComponentNotFoundError";
-  kind = "Http";
-  status = 404;
-  constructor(component) {
-    super(`Unable to find component: [${component}].`);
-  }
-};
-var InvalidLiveRequestError = class extends LiveError {
-  name = "InvalidLiveRequestError";
-  kind = "Http";
-  status = 400;
-};
+// flash.ts
+function trackFlash(session, { saved = true } = {}) {
+  if (session === void 0) return () => void 0;
+  const before = new Set(session.get("_flash.new", []));
+  return (redirected) => {
+    if (redirected) return;
+    const flashed = session.get("_flash.new", []);
+    const fresh = flashed.filter((key) => !before.has(key));
+    if (fresh.length === 0) return;
+    session.put("_flash.new", flashed.filter((key) => before.has(key)));
+    if (!saved) return session.forget(...fresh);
+    const old = session.get("_flash.old", []);
+    session.put("_flash.old", [...old, ...fresh.filter((key) => !old.includes(key))]);
+  };
+}
 
 // html.ts
 var ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#039;" };
 function escapeAttribute(value) {
   return value.replace(/[&<>"']/g, (char) => ESCAPES[char]);
 }
+function stripTags(html) {
+  return html.replace(/<[^>]*>/g, "");
+}
 var VOID = /* @__PURE__ */ new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "source", "track", "wbr"]);
 var RAW_TEXT = /* @__PURE__ */ new Set(["script", "style", "textarea", "title"]);
 var TOKEN = /<\/([A-Za-z][\w:-]*)\s*>|<([A-Za-z][\w:-]*)(?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*\s*(\/?)>/g;
@@ -327,6 +510,15 @@ function requestScope() {
   const container = currentContainer() ?? Container.getInstance();
   return container?.bound(TestRequestScope) === true ? container.make(TestRequestScope) : (run) => run();
 }
+function currentSession() {
+  const container = currentContainer();
+  if (container?.bound(Session) !== true) return void 0;
+  try {
+    return container.make(Session);
+  } catch {
+    return void 0;
+  }
+}
 var Testable = class _Testable {
   constructor(manager, scope, result) {
     this.manager = manager;
@@ -381,7 +573,12 @@ var Testable = class _Testable {
     return this.#update({}, [{ method: "$refresh", params: [] }]);
   }
   async #update(updates, calls) {
-    const result = await this.scope(() => this.manager.updateComponent(this.#snapshot, updates, calls));
+    const result = await this.scope(async () => {
+      const flashed = trackFlash(currentSession(), { saved: false });
+      const updated = await this.manager.updateComponent(this.#snapshot, updates, calls);
+      flashed(updated.effects.redirect !== void 0);
+      return updated;
+    });
     this.#snapshot = JSON.stringify(result.snapshot);
     if (result.html !== void 0) this.#html = result.html;
     this.#effects = result.effects;
@@ -411,6 +608,17 @@ var Testable = class _Testable {
     for (const value of values) if (!this.html().includes(value)) fail(`Failed asserting that [${value}] is in the rendered HTML.`, this.html(), value);
     return this;
   }
+  /** Each value, HTML-escaped, appears in the rendered text: the HTML with its tags stripped (Livewire's assertSeeText). */
+  assertSeeText(...values) {
+    const text = stripTags(this.html());
+    for (const value of values) if (!text.includes(escapeAttribute(value))) fail(`Failed asserting that [${value}] is in the rendered text.`, text, value);
+    return this;
+  }
+  assertDontSeeText(...values) {
+    const text = stripTags(this.html());
+    for (const value of values) if (text.includes(escapeAttribute(value))) fail(`Failed asserting that [${value}] is not in the rendered text.`, text, value);
+    return this;
+  }
   assertDispatched(name, params) {
     const dispatched = (this.#effects.dispatches ?? []).filter((event) => event.name === name);
     if (dispatched.length === 0) fail(`Failed asserting that an event [${name}] was dispatched.`, this.#effects.dispatches ?? [], name);
@@ -477,16 +685,17 @@ var Live = Object.assign(LiveComponent, {
 });
 
 // LiveComponentManager.ts
-import { AsyncLocalStorage } from "async_hooks";
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
 import { randomBytes } from "crypto";
 import {
   ClassRegistry,
   ConfigRepository,
-  CurrentRoute,
+  CurrentRoute as CurrentRoute2,
   Encrypter,
   HttpRequest,
   Redirector,
   Router,
+  Session as Session2,
   ViewFactory
 } from "@orieljs/contracts";
 import { currentContainer as currentContainer2 } from "@orieljs/container";
@@ -541,10 +750,12 @@ async function discover(directory) {
 }
 
 // persistent.ts
-var PERSISTENT_MIDDLEWARE = ["auth", "verified", "guest"];
+import { CurrentRoute } from "@orieljs/contracts";
+var PERSISTENT_MIDDLEWARE = ["auth", "verified", "guest", "can"];
+var ROUTER_METHODS = ["getRoutesByMatchOrder", "getPatterns", "getPatternVersion", "getMiddleware", "getMiddlewareGroups", "substituteBindings"];
 function canMatch(router) {
   const methods = router;
-  return ["getRoutesByMatchOrder", "getPatterns", "getPatternVersion", "getMiddleware", "getMiddlewareGroups"].every((name) => typeof methods[name] === "function");
+  return ROUTER_METHODS.every((name) => typeof methods[name] === "function");
 }
 function isMatchingRoute(route) {
   const candidate = route;
@@ -573,7 +784,7 @@ function expand(references, aliases, groups, out = [], visiting = /* @__PURE__ *
   }
   return out;
 }
-function persistentMiddleware(router, persistent, method, path) {
+function persistentPass(router, persistent, method, path) {
   if (!canMatch(router)) throw new LiveError("Live re-applies the page route's middleware to updates, which needs Oriel's router.");
   const routes = router.getRoutesByMatchOrder();
   if (!Array.isArray(routes) || !routes.every(isMatchingRoute)) throw new LiveError("Live re-applies the page route's middleware to updates, which needs Oriel's routes.");
@@ -581,187 +792,144 @@ function persistentMiddleware(router, persistent, method, path) {
   const target = routePath(path);
   const patterns = router.getPatterns();
   const version = router.getPatternVersion();
-  const route = routes.find((candidate) => candidate.methods.includes(verb) && candidate.match(target, patterns, version) !== void 0);
-  if (route === void 0) return [];
+  let matched;
+  for (const candidate of routes) {
+    const values2 = candidate.methods.includes(verb) ? candidate.match(target, patterns, version) : void 0;
+    if (values2 !== void 0) {
+      matched = { route: candidate, values: values2 };
+      break;
+    }
+  }
+  if (matched === void 0) return void 0;
+  const { route, values } = matched;
   const aliases = router.getMiddleware();
   const groups = router.getMiddlewareGroups();
   const wanted = new Set(persistent.flatMap((name) => Object.hasOwn(aliases, name) ? [aliases[name]] : []));
   const excluded = new Set(expand(route.excludedMiddleware(), aliases, groups).map((entry) => entry.cls));
   const ids = /* @__PURE__ */ new Map();
   const seen = /* @__PURE__ */ new Set();
-  return expand(route.gatherMiddleware(), aliases, groups).filter((entry) => {
+  const middleware = expand(route.gatherMiddleware(), aliases, groups).filter((entry) => {
     if (!ids.has(entry.cls)) ids.set(entry.cls, ids.size);
     const key = `${ids.get(entry.cls)}:${entry.parameters.join(",")}`;
     if (!wanted.has(entry.cls) || excluded.has(entry.cls) || seen.has(key)) return false;
     seen.add(key);
     return true;
   });
+  const early = new Set(expand(["web", "api"], aliases, groups).map((entry) => entry.cls));
+  for (const name of ["auth", "guest"]) if (Object.hasOwn(aliases, name)) early.add(aliases[name]);
+  const before = middleware.filter((entry) => early.has(entry.cls));
+  const after = middleware.filter((entry) => !early.has(entry.cls));
+  return { router, route, values, middleware: [...before, ...after], at: before.length };
 }
-async function throughMiddleware(container, request, middleware, destination) {
+function persistentMiddleware(router, persistent, method, path) {
+  return [...persistentPass(router, persistent, method, path)?.middleware ?? []];
+}
+function currentRoute(container) {
+  if (!container.bound(CurrentRoute)) return void 0;
+  try {
+    return container.make(CurrentRoute);
+  } catch {
+    return void 0;
+  }
+}
+async function throughMiddleware(container, request, pass, destination) {
+  const original = currentRoute(container);
+  const page = { route: pass.route, parameters: { ...pass.values }, middleware: [] };
+  let swapped = false;
+  const show = () => {
+    container.instance(CurrentRoute, page);
+    swapped = true;
+  };
+  const restore = () => {
+    if (!swapped) return;
+    if (original === void 0) container.forgetInstance(CurrentRoute);
+    else container.instance(CurrentRoute, original);
+    swapped = false;
+  };
   let ran;
   const run = async (index) => {
-    if (index === middleware.length) {
+    if (index === pass.at) Object.assign(page.parameters, await pass.router.substituteBindings(pass.route, pass.values, container));
+    if (index === pass.middleware.length) {
+      restore();
       ran = { result: await destination() };
       return new Response(null, { status: 204 });
     }
-    const { cls, parameters } = middleware[index];
+    const { cls, parameters } = pass.middleware[index];
     const instance = container.make(cls);
     const next = () => run(index + 1);
     return instance.handle(request, next, ...parameters);
   };
-  const response = await run(0);
-  return ran ? ran.result : response;
+  show();
+  try {
+    const response = await run(0);
+    return ran ? ran.result : response;
+  } finally {
+    restore();
+  }
 }
 
-// security.ts
-import { Collection as Collection2 } from "@orieljs/collections";
-
-// synthesizers.ts
-import { Collection } from "@orieljs/collections";
-function isModel(value) {
-  if (typeof value !== "object" || value === null) return false;
-  const candidate = value;
-  return typeof candidate.getKey === "function" && typeof candidate.getKeyName === "function" && typeof candidate.getTable === "function" && typeof candidate.exists === "boolean";
+// WithPagination.ts
+import { AsyncLocalStorage } from "async_hooks";
+var PAGINATED = /* @__PURE__ */ Symbol.for("oriel:live.pagination");
+function toPage(value) {
+  const page = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : Number.NaN;
+  return Number.isFinite(page) && page >= 1 ? Math.min(Math.floor(page), Number.MAX_SAFE_INTEGER) : 1;
 }
-var isPlainObject = (value) => {
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
-};
-var isTuple = (value) => Array.isArray(value) && value.length === 2 && typeof value[1] === "object" && value[1] !== null && !Array.isArray(value[1]) && typeof value[1].s === "string";
-function classNameOf(registry, cls) {
-  return registry.nameOf(cls) ?? registry.register(cls);
+async function hook(instance, name, ...args) {
+  const method = instance[name];
+  if (typeof method === "function") await method.apply(instance, args);
 }
-function dehydrate(value, registry, path, seen = /* @__PURE__ */ new Set()) {
-  switch (typeof value) {
-    case "undefined":
-      return [null, { s: "u" }];
-    case "string":
-    case "boolean":
-      return value;
-    case "number":
-      if (!Number.isFinite(value)) throw new LiveError(`Property [${path}] is ${value}: Live state must be JSON (finite numbers only).`);
-      return value;
-    case "bigint":
-    case "symbol":
-    case "function":
-      throw new LiveError(`Property [${path}] holds a ${typeof value}: Live state may only hold primitives, arrays, plain objects, Dates, models and collections.`);
-  }
-  if (value === null) return null;
-  const object = value;
-  if (seen.has(object)) throw new LiveError(`Property [${path}] contains a circular reference.`);
-  seen.add(object);
-  try {
-    if (object instanceof Date) return [object.toISOString(), { s: "dt" }];
-    if (Array.isArray(object)) return [object.map((item, i) => dehydrate(item, registry, `${path}.${i}`, seen)), { s: "arr" }];
-    if (isModel(object)) {
-      const name = classNameOf(registry, object.constructor);
-      if (!object.exists) throw new LiveError(`Property [${path}] holds an unsaved [${name}] model: only saved models can be kept between requests.`);
-      return [null, { s: "mdl", class: name, key: object.getKey() }];
+function WithPagination(Base) {
+  class WithPaginationMixin extends Base {
+    page = 1;
+    nextPage() {
+      return this.setPage(toPage(this.page) + 1);
     }
-    if (object instanceof Collection) {
-      const items = object.all();
-      const first = items[0];
-      if (items.length > 0 && isModel(first) && items.every((item) => isModel(item) && item.constructor === first.constructor)) {
-        for (const [i, item] of items.entries()) {
-          if (!item.exists) throw new LiveError(`Property [${path}.${i}] holds an unsaved model.`);
-        }
-        const name = classNameOf(registry, first.constructor);
-        return [null, { s: "elcln", class: name, keys: items.map((item) => item.getKey()) }];
-      }
-      return [items.map((item, i) => dehydrate(item, registry, `${path}.${i}`, seen)), { s: "clctn" }];
+    previousPage() {
+      return this.setPage(Math.max(toPage(this.page) - 1, 1));
     }
-    if (isPlainObject(object)) {
-      const out = {};
-      for (const [key, item] of Object.entries(object)) out[key] = dehydrate(item, registry, `${path}.${key}`, seen);
-      return [out, { s: "obj" }];
+    gotoPage(page) {
+      return this.setPage(page);
     }
-    const type = object.constructor?.name || "object";
-    throw new LiveError(
-      `Property [${path}] holds a [${type}] instance: Live state may only hold primitives, arrays, plain objects, Dates, models and collections.`
-    );
-  } finally {
-    seen.delete(object);
-  }
-}
-function modelClass(registry, name) {
-  if (typeof name !== "string" || !registry.has(name)) throw new LiveError(`Unable to hydrate the [${String(name)}] model: it is not registered.`);
-  return registry.resolve(name);
-}
-async function hydrate(value, registry) {
-  if (!isTuple(value)) return value;
-  const [inner, meta] = value;
-  switch (meta.s) {
-    case "u":
-      return void 0;
-    case "dt":
-      return new Date(String(inner));
-    case "arr":
-      return Promise.all(inner.map((item) => hydrate(item, registry)));
-    case "clctn":
-      return new Collection(await Promise.all(inner.map((item) => hydrate(item, registry))));
-    case "obj": {
-      const out = {};
-      for (const [key, item] of Object.entries(inner)) {
-        Object.defineProperty(out, key, { value: await hydrate(item, registry), enumerable: true, writable: true, configurable: true });
-      }
-      return out;
+    resetPage() {
+      return this.setPage(1);
     }
-    case "mdl":
-      return modelClass(registry, meta.class).findOrFail(meta.key);
-    case "elcln": {
-      const cls = modelClass(registry, meta.class);
-      const keys = meta.keys ?? [];
-      const keyName = new cls().getKeyName();
-      const found = [...await cls.query().whereIn(keyName, keys).get()];
-      const byKey = new Map(found.map((model) => [String(model.getKey()), model]));
-      return new Collection(keys.map((key) => byKey.get(String(key))).filter((model) => model !== void 0));
+    async setPage(page) {
+      const next = toPage(page);
+      await hook(this, "updatingPage", next);
+      this.page = next;
+      await hook(this, "updatedPage", next);
     }
   }
-  throw new LiveError(`Unknown snapshot value type [${String(meta.s)}].`);
+  Object.defineProperty(WithPaginationMixin.prototype, PAGINATED, { value: true });
+  return WithPaginationMixin;
 }
-
-// security.ts
-var HOOKS = /* @__PURE__ */ new Set(["constructor", "render", "mount", "boot", "booted", "hydrate", "dehydrate", "updating", "updated", "rendering", "rendered", "exception"]);
-var HOOK_PREFIX = /^(updating|updated|hydrate|dehydrate)[A-Z_]/;
-var UNSAFE_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "prototype", "constructor"]);
-var BASE_API = new Set(Object.getOwnPropertyNames(Component.prototype));
-var INDEX = /^(?:0|[1-9]\d*)$/;
-function isArraySlot(array, segment) {
-  return INDEX.test(segment) && Number(segment) <= array.length;
+function isPaginated(component) {
+  return component[PAGINATED] === true;
 }
-function isCallable(instance, method) {
-  if (method === "" || method.startsWith("_") || method.startsWith("$") || method.startsWith("#")) return false;
-  if (HOOKS.has(method) || HOOK_PREFIX.test(method) || BASE_API.has(method)) return false;
-  if (lockedOf(instance.constructor).has(method)) return false;
-  const isBase = (proto) => proto === Component.prototype || proto === Object.prototype;
-  for (let proto = Object.getPrototypeOf(instance); proto !== null && !isBase(proto); proto = Object.getPrototypeOf(proto)) {
-    const descriptor = Object.getOwnPropertyDescriptor(proto, method);
-    if (descriptor !== void 0) return typeof descriptor.value === "function";
-  }
-  return false;
+var rendering = new AsyncLocalStorage();
+function renderPaginated(component, url, run) {
+  return rendering.run(isPaginated(component) ? { component, url } : void 0, run);
 }
-function isUpdatable(instance, path) {
-  const segments = path.split(".");
-  const root = segments[0];
-  if (root === "" || root.startsWith("_") || segments.some((segment) => segment === "" || UNSAFE_SEGMENTS.has(segment))) return false;
-  if (!Object.hasOwn(instance, root)) return false;
-  const descriptor = Object.getOwnPropertyDescriptor(instance, root);
-  if (!descriptor.enumerable || descriptor.get !== void 0) return false;
-  const cls = instance.constructor;
-  if (lockedOf(cls).has(root) || computedOf(cls).has(root)) return false;
-  let node = descriptor.value;
-  for (const segment of segments.slice(1)) {
-    if (isModel(node) || node instanceof Collection2) return false;
-    if (Array.isArray(node) && !isArraySlot(node, segment)) return false;
-    if (typeof node !== "object" || node === null || !Object.hasOwn(node, segment)) return true;
-    node = node[segment];
-  }
-  return !isModel(node) && !(node instanceof Collection2);
+function outsidePagination(run) {
+  return rendering.run(void 0, run);
 }
+var livePaginationState = {
+  currentPage(pageName) {
+    const current = rendering.getStore();
+    if (current === void 0 || pageName !== "page") return void 0;
+    const page = toPage(current.component.page);
+    current.component.page = page;
+    return page;
+  },
+  currentPath() {
+    return rendering.getStore()?.url;
+  }
+};
 
 // LiveComponentManager.ts
-var renderContext = new AsyncLocalStorage();
-var pageRequest = new AsyncLocalStorage();
+var renderContext = new AsyncLocalStorage2();
+var pageRequest = new AsyncLocalStorage2();
 function optional(container, token2) {
   if (!container.bound(token2)) return void 0;
   try {
@@ -774,7 +942,7 @@ var isRecord = (value) => typeof value === "object" && value !== null && !Array.
 function setOwn(object, key, value) {
   Object.defineProperty(object, key, { value, enumerable: true, writable: true, configurable: true });
 }
-async function hook(instance, name, ...args) {
+async function hook2(instance, name, ...args) {
   const method = instance[name];
   if (typeof method === "function") await method.apply(instance, args);
 }
@@ -825,7 +993,7 @@ var LiveComponentManager = class {
       setOwn(context.children, childKey, existing);
       return `<${existing[0]} o:id="${escapeAttribute(existing[1])}"></${existing[0]}>`;
     }
-    const result = await this.mountComponent(component, params);
+    const result = await outsidePagination(() => this.mountComponent(component, params));
     setOwn(context.children, childKey, [result.tag, result.snapshot.memo.id]);
     return result.html;
   }
@@ -837,14 +1005,14 @@ var LiveComponentManager = class {
     const state = stateOf(instance);
     state.id = randomBytes(15).toString("base64url");
     state.name = name;
-    await hook(instance, "boot");
+    await hook2(instance, "boot");
     for (const [property, value] of Object.entries(params)) {
       if (Object.hasOwn(instance, property)) instance[property] = value;
     }
     this.prepareComputed(instance);
-    await hook(instance, "mount", params);
     const request = optional(this.container(), HttpRequest);
     const page = pageRequest.getStore() ?? { path: request?.path() ?? "", method: request?.method() ?? "GET" };
+    await renderPaginated(instance, this.pageUrl(page.path), () => hook2(instance, "mount", params));
     const memo = { id: state.id, name, path: page.path, method: page.method, children: {}, errors: {} };
     const { html, tag } = await this.render(instance, memo, {});
     const effects = this.effects(instance);
@@ -872,22 +1040,24 @@ var LiveComponentManager = class {
     state.id = snapshot.memo.id;
     state.name = snapshot.memo.name;
     state.errors = { ...snapshot.memo.errors };
-    await hook(instance, "boot");
+    await hook2(instance, "boot");
     const registry = this.registry();
     for (const [property, value] of Object.entries(snapshot.data)) {
       Object.defineProperty(instance, property, { value: await hydrate(value, registry), enumerable: true, writable: true, configurable: true });
     }
     this.prepareComputed(instance);
-    await hook(instance, "hydrate");
     const returns = [];
-    try {
-      for (const [path, value] of Object.entries(updates)) await this.applyUpdate(instance, path, value);
-      for (const call of calls) returns.push(await this.call(instance, call.method, call.params));
-    } catch (error) {
-      const errors = error.errors;
-      if (error.kind !== "Validation" || !isRecord(errors)) throw error;
-      state.errors = { ...errors };
-    }
+    await renderPaginated(instance, this.pageUrl(snapshot.memo.path), async () => {
+      await hook2(instance, "hydrate");
+      try {
+        for (const [path, value] of Object.entries(updates)) await this.applyUpdate(instance, path, value);
+        for (const call of calls) returns.push(await this.call(instance, call.method, call.params));
+      } catch (error) {
+        const errors = error.errors;
+        if (error.kind !== "Validation" || !isRecord(errors)) throw error;
+        state.errors = { ...errors };
+      }
+    });
     const memo = { ...snapshot.memo, children: { ...snapshot.memo.children } };
     const effects = this.effects(instance);
     let html;
@@ -902,31 +1072,36 @@ var LiveComponentManager = class {
     return { instance, snapshot: await this.snapshot(instance, memo), effects, html, tag };
   }
   /**
-   * The route action of POST /oriel/live/update. Each component's update runs behind the auth middleware of the route
-   * that rendered its page (Livewire's persistent middleware): a signed-out tab gets a 401, never the action. When a
-   * middleware answers instead (a redirect), that is the response.
+   * The route action of POST /oriel/live/update. Each component's update runs behind the persistent middleware of the
+   * route that rendered its page (Livewire's): `auth`, `verified`, `guest` and `can`, with the page route's parameters
+   * bound again. A signed-out tab gets a 401, a revoked ability a 403 and a deleted model a 404, before the component
+   * hydrates. When a middleware answers instead (a redirect), that is the response. A key first flashed during the
+   * update shows in this response only, unless the update redirects.
    */
   async handle(request) {
     if (!this.isLiveRequest(request)) throw new InvalidLiveRequestError("Live update requests need the X-Oriel-Live header.");
     const container = this.container();
     const persistent = optional(container, ConfigRepository)?.get("live.persistent_middleware", PERSISTENT_MIDDLEWARE) ?? PERSISTENT_MIDDLEWARE;
     const components = [];
+    const flashed = trackFlash(optional(container, Session2));
     for (const component of this.payload(request).components) {
       const { memo } = this.verify(component.snapshot);
-      const middleware = persistentMiddleware(container.make(Router), persistent, memo.method, memo.path);
+      const pass = persistentPass(container.make(Router), persistent, memo.method, memo.path);
+      const update = () => this.updateComponent(component.snapshot, component.updates, component.calls);
       const result = await pageRequest.run(
         { path: memo.path, method: memo.method },
-        () => throughMiddleware(container, request, middleware, () => this.updateComponent(component.snapshot, component.updates, component.calls))
+        () => pass === void 0 || pass.middleware.length === 0 ? update() : throughMiddleware(container, request, pass, update)
       );
       if (result instanceof Response) return result;
       components.push({ snapshot: JSON.stringify(result.snapshot), effects: result.effects });
     }
+    flashed(components.some((component) => component.effects.redirect !== void 0));
     return { components };
   }
   /** A full-page component (Route.get('/counter', Counter)): mounted with the route parameters, inside the layout. */
   async page(component) {
     const container = this.container();
-    const params = { ...optional(container, CurrentRoute)?.parameters ?? {} };
+    const params = { ...optional(container, CurrentRoute2)?.parameters ?? {} };
     const cls = component.constructor;
     const result = await this.mountComponent(cls, params, component);
     const redirect = result.effects.redirect;
@@ -995,8 +1170,8 @@ var LiveComponentManager = class {
     const [root, ...rest] = path.split(".");
     const key = rest.length > 0 ? rest.join(".") : void 0;
     const studly = Str2.studly(root);
-    await hook(instance, "updating", path, value);
-    await hook(instance, `updating${studly}`, value, key);
+    await hook2(instance, "updating", path, value);
+    await hook2(instance, `updating${studly}`, value, key);
     const target = instance;
     if (rest.length === 0) target[root] = value;
     else {
@@ -1014,8 +1189,8 @@ var LiveComponentManager = class {
       assertSlot(node, last);
       Object.defineProperty(node, last, { value, enumerable: true, writable: true, configurable: true });
     }
-    await hook(instance, "updated", path, value);
-    await hook(instance, `updated${studly}`, value, key);
+    await hook2(instance, "updated", path, value);
+    await hook2(instance, `updated${studly}`, value, key);
   }
   /** Runs one call from the browser: a magic action, an event, or a public method. Returns its return value. */
   async call(instance, method, params) {
@@ -1043,18 +1218,35 @@ var LiveComponentManager = class {
     if (!isCallable(instance, method)) throw new MethodNotCallableError(method, name);
     return instance[method](...params);
   }
-  /** Renders the component (rendering/rendered hooks, nested children tracked) and checks for a single root. */
+  /**
+   * Renders the component (rendering/rendered hooks, nested children tracked) and checks for a single root. A
+   * WithPagination component's page and page URL are what paginate() reads while it renders, as in its mount() and in
+   * its update's hooks and actions.
+   */
   async render(instance, memo, previous) {
-    await hook(instance, "rendering");
+    await hook2(instance, "rendering");
     const context = { previous, children: {}, index: 0 };
-    const html = await renderContext.run(context, async () => {
-      const output = await instance.render();
-      return typeof output === "string" ? output : this.container().make(ViewFactory).renderToString(output);
-    });
-    await hook(instance, "rendered", html);
+    const html = await renderContext.run(
+      context,
+      () => renderPaginated(instance, this.pageUrl(memo.path), async () => {
+        const output = await instance.render();
+        return typeof output === "string" ? output : this.container().make(ViewFactory).renderToString(output);
+      })
+    );
+    await hook2(instance, "rendered", html);
     memo.children = context.children;
     return { html: html.trim(), tag: rootTag(html, memo.name) };
   }
+  /** The absolute URL of the page a memo path belongs to, on the current request's origin ('/' + path without one). */
+  pageUrl(path) {
+    const relative3 = `/${path.replace(/^\/+/, "")}`;
+    const url = optional(this.container(), HttpRequest)?.url();
+    try {
+      return url === void 0 ? relative3 : new URL(relative3, url).href;
+    } catch {
+      return relative3;
+    }
+  }
   /** Dispatches, redirects: the effects every response carries. */
   effects(instance) {
     const state = stateOf(instance);
@@ -1073,7 +1265,7 @@ var LiveComponentManager = class {
   }
   /** dehydrate() hook, then the state as snapshot data, the error bag, and the checksum over both. */
   async snapshot(instance, memo) {
-    await hook(instance, "dehydrate");
+    await hook2(instance, "dehydrate");
     const registry = this.registry();
     const data = {};
     for (const [property, value] of Object.entries(instance)) data[property] = dehydrate(value, registry, `${memo.name}.${property}`);
@@ -1083,7 +1275,7 @@ var LiveComponentManager = class {
 };
 
 // LiveServiceProvider.ts
-import { ConfigRepository as ConfigRepository3, ConsoleKernel, HttpRequest as HttpRequest2, LiveManager as LiveManager4, Router as Router2 } from "@orieljs/contracts";
+import { ConfigRepository as ConfigRepository3, ConsoleKernel, HttpRequest as HttpRequest2, LiveManager as LiveManager4, PaginationState, Router as Router2 } from "@orieljs/contracts";
 import { inject as inject4 } from "@orieljs/container";
 import { ServiceProvider } from "@orieljs/support";
 
@@ -1160,6 +1352,7 @@ var LiveServiceProvider = class extends ServiceProvider {
     this.mergeConfigFrom({ class_path: this.app.appPath("Live"), layout: "components.layouts.app", persistent_middleware: [...PERSISTENT_MIDDLEWARE] }, "live");
     this.app.singleton(LiveComponentManager, () => new LiveComponentManager(this.app));
     this.app.singleton(LiveManager4, (container) => container.make(LiveComponentManager));
+    this.app.singleton(PaginationState, () => livePaginationState);
   }
   async boot() {
     const manager = this.app.make(LiveComponentManager);
@@ -1173,6 +1366,42 @@ var LiveServiceProvider = class extends ServiceProvider {
     }
   }
 };
+
+// Pagination.ts
+function urlWindow(current, last, onEachSide) {
+  const range = (from, to) => Array.from({ length: Math.max(to - from + 1, 0) }, (_, index) => from + index);
+  if (last < onEachSide * 2 + 8) return range(1, last);
+  const size = onEachSide + 4;
+  if (current <= size) return [...range(1, size + onEachSide), "...", ...range(last - 1, last)];
+  if (current > last - size) return [...range(1, 2), "...", ...range(last - (size + (onEachSide - 1)), last)];
+  return [...range(1, 2), "...", ...range(current - onEachSide, current + onEachSide), "...", ...range(last - 1, last)];
+}
+function button(label, action, attributes = "") {
+  const live2 = action === void 0 ? " disabled" : ` o:click="${escapeAttribute(action)}"`;
+  return `<button type="button" class="btn btn-secondary"${attributes}${live2}>${escapeAttribute(label)}</button>`;
+}
+function Pagination({ paginator, class: className }) {
+  if (typeof paginator.nextCursor === "function") {
+    throw new LiveError("<Pagination> needs paginate() or simplePaginate(): a cursor paginator has no page numbers.");
+  }
+  const current = paginator.currentPage();
+  const onFirst = paginator.onFirstPage();
+  const hasMore = paginator.hasMorePages();
+  if (onFirst && !hasMore) return { toHtml: () => "" };
+  const parts = [button("\xAB Previous", onFirst ? void 0 : "previousPage")];
+  if (typeof paginator.lastPage === "function") {
+    const onEachSide = Number.isInteger(paginator.onEachSideCount) && paginator.onEachSideCount >= 0 ? paginator.onEachSideCount : 3;
+    for (const page of urlWindow(current, paginator.lastPage(), onEachSide)) {
+      if (page === "...") parts.push('<span aria-hidden="true">...</span>');
+      else if (page === current) parts.push(`<button type="button" class="btn" aria-current="page" disabled>${page}</button>`);
+      else parts.push(button(String(page), `gotoPage(${page})`, ` aria-label="Go to page ${page}"`));
+    }
+  }
+  parts.push(button("Next \xBB", hasMore ? "nextPage" : void 0));
+  const classes = className === void 0 || className === "" ? "" : ` class="${escapeAttribute(className)}"`;
+  const html = `<nav aria-label="Pagination"${classes}>${parts.join("")}</nav>`;
+  return { toHtml: () => html };
+}
 export {
   Component,
   Computed,
@@ -1188,11 +1417,13 @@ export {
   MethodNotCallableError,
   On,
   PERSISTENT_MIDDLEWARE,
+  Pagination,
   PendingEvent,
   PropertyNotUpdatableError,
   TestRequestScope,
   Testable,
   UPDATE_URI,
+  WithPagination,
   componentName,
   live,
   persistentMiddleware