@zerotal/flow 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -10,6 +10,56 @@ between minor versions.
 
 ## [Unreleased]
 
+## [1.3.0] — 2026-08-09
+
+### Fixed
+
+- **An `@expose`d action on a shared page base no longer disappears from the allowlist.** Bun
+  1.3.x does not reliably run a method decorator's `addInitializer` callbacks: when a subclass
+  declared a decorated field, the base class's method initializers never ran at all. So a page
+  base carrying `@expose guard()` lost that action the moment any subclass added one `@expose`
+  field — and since the un-`@expose`d action check is fatal, clicking a perfectly legitimate
+  button was rejected at runtime with a message pointing at the wrong cause. It reproduced with a
+  bare `class Sub extends Base` and no mixin anywhere. `@expose` (methods), `@task`,
+  `@renderless`, `@on` and `@computed` were all affected.
+
+  Method and getter decorators now tag the function in the decorator body — which always runs,
+  with the right name — and the readers scan the prototype chain for tagged members, registering
+  against the **declaring** prototype so inheritance resolves through the existing chain walk.
+  Registration no longer requires an instance to have been constructed, so `getExposedMethods()`
+  is correct on a class that has never been instantiated.
+
+### Changed — BREAKING
+
+- **`ComponentWith(...)` is replaced by the `Component.using(...)` static.** Mixin composition is
+  now a property of the base class rather than a helper shipped alongside it, so there is one
+  idiom to learn and nothing extra to import.
+
+  ```tsx
+  // before
+  import { ComponentWith, Pagination } from "@zerotal/flow";
+  class PostsPage extends ComponentWith(Pagination, FileUploads) {}
+
+  // after
+  import { Component, Pagination } from "@zerotal/flow";
+  class PostsPage extends Component.using(Pagination, FileUploads) {}
+  ```
+
+  Run `bun run scripts/codemod-mixin-composition.ts` to rewrite call sites and imports.
+
+  How mixins are **authored** is unchanged — `<T extends Constructor<Component>>(Base: T) => …`
+  still works exactly as before, and every shipped mixin keeps its signature. The `Constructor`
+  and `Mixin` types are still exported; `Compose` (the type of `Component.using`) joins them.
+
+### Added
+
+- **`using` composes onto any class in the chain, not just `Component`.** An app-level base can
+  now carry mixins without being flattened out of the prototype chain — `AdminPage.using(Pagination)`
+  keeps `AdminPage` in the lineage. `ComponentWith` hardcoded `Component`, so this previously
+  required hand-nesting (`Pagination(AdminPage)`).
+- **Composition chains.** The composed class carries `using` itself, so
+  `Component.using(a, b).using(c, d)` works past the 8-mixin overload set.
+
 ## [1.1.0] — 2026-08-08
 
 ### Fixed

package/README.md

@@ -122,7 +122,7 @@ Action helpers available inside any exposed method include `this.flash()`, `this
 
 **Headless (unstyled, accessible) primitives:** `Switch`, `Checkbox`, `Select`, `RadioGroup`, `Listbox`, `Combobox`, `Disclosure`, `Accordion`, `Popover`, `Field`, `Label`, `Description`, `Fieldset`, `Legend`.
 
-**Mixins & helpers:** compose features with `ComponentWith(Pagination, FileUploads)` — the `Pagination` mixin (`page` state + `nextPage`/`gotoPage`/…, paired with `Model.paginate()` and rendered by `<Pager>`) and the `FileUploads` mixin (`removeUpload`, paired with `<FileUpload>` + `TemporaryUploadedFile`). Also `Form` + `registerForm`, the `paginate` helper + `Paginator` type, and `Layout` for shared page shells.
+**Mixins & helpers:** compose features with `Component.using(Pagination, FileUploads)` — the `Pagination` mixin (`page` state + `nextPage`/`gotoPage`/…, paired with `Model.paginate()` and rendered by `<Pager>`) and the `FileUploads` mixin (`removeUpload`, paired with `<FileUpload>` + `TemporaryUploadedFile`). Also `Form` + `registerForm`, the `paginate` helper + `Paginator` type, and `Layout` for shared page shells.
 
 **Slots:** a child component's plain children are its default slot; a `slots={{ header, footer }}` prop supplies named slots. The child places them with `this.slot(name)` / `this.slot()` and branches on `this.hasSlot(name)` — ideal for reusable shells (cards, modals, panels). Slot markup renders in the parent's scope and is carried, signed, in the child's snapshot.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/flow",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "license": "MIT",
   "maturity": "experimental",
   "private": false,
@@ -45,14 +45,14 @@
     "@alpinejs/morph": "^3.14.9",
     "@alpinejs/persist": "^3.14.9",
     "@alpinejs/resize": "^3.14.9",
-    "@zerotal/core": "1.1.0",
-    "@zerotal/orm": "1.1.0",
-    "@zerotal/validator": "1.1.0",
+    "@zerotal/core": "1.3.0",
+    "@zerotal/orm": "1.3.0",
+    "@zerotal/validator": "1.3.0",
     "alpinejs": "^3.14.9",
     "typescript": "^5.8.0"
   },
   "devDependencies": {
-    "@zerotal/broadcasting": "1.1.0",
+    "@zerotal/broadcasting": "1.3.0",
     "@types/alpinejs": "^3.13.10",
     "@types/alpinejs__anchor": "^3.13.1",
     "@types/alpinejs__collapse": "^3.13.4",

package/src/Component.ts

@@ -23,6 +23,8 @@ import { ValidationError } from "./validation.ts";
 import type { ValidationRules } from "./validation.ts";
 import { resolveUploadValue } from "./uploads/TemporaryUploadedFile.ts";
 import { toScriptJson } from "./utils.ts";
+import { _compose } from "./mixins.ts";
+import type { Compose } from "./mixins.ts";
 import { _validateEventPayload } from "./events.ts";
 import type { FlowEvents, EventName, EventArgs } from "./events.ts";
 import { route, request, safeRedirectPath, HttpContext } from "@zerotal/core";
@@ -343,6 +345,54 @@ export abstract class Component {
    */
   static readonly __isFlowPage = true as const;
 
+  /**
+   * Compose one or more feature mixins onto this class, folding them left-to-right, so a page can
+   * be built from focused, reusable behaviours instead of one bloated class.
+   *
+   * @remarks
+   * Each mixin receives the accumulated base and returns an extended class, so `Component`'s full
+   * surface (`flash()`, `redirect()`, `validate()`, the client magics, …) and every mixin's
+   * `@expose`/`@locked` members flow through to the final page — fully type-checked. Mixin props
+   * register on the mixin prototype, which sits in the page's prototype chain, so snapshot,
+   * reactivity, client writes, and `@url` sync all work exactly as for props declared on the page.
+   *
+   * `using` composes onto whatever class it is called on, so it also works on an intermediate base
+   * (`AdminPage.using(Pagination)` keeps `AdminPage` in the chain), and the composed class carries
+   * `using` itself, so `Component.using(a, b).using(c)` chains past the 8-mixin overload set.
+   *
+   * Pages composed this way render via the runtime path rather than the AOT compiler (which only
+   * statically sees a page's own `extends Component` plus locally-declared members) — the same
+   * fallback complex pages already use; behaviour is identical, you just don't get the
+   * ahead-of-time compile step for that page.
+   *
+   * @param mixins - Mixin factories applied left-to-right (each takes the prior result as its base).
+   * @returns A class extending this one with every mixin's members mixed in.
+   *
+   * @example
+   * ```tsx
+   * // app/flow/mixins/pagination.ts
+   * import { Component, expose, type Constructor } from "@zerotal/flow";
+   *
+   * export function Pagination<T extends Constructor<Component>>(Base: T) {
+   *   abstract class WithPagination extends Base {
+   *     @expose page = 1;
+   *     @expose next() { this.page++; }
+   *   }
+   *   return WithPagination;
+   * }
+   *
+   * // app/flow/UsersPage.tsx
+   * class UsersPage extends Component.using(Pagination) {
+   *   override async render() {
+   *     return <div data-flow-root>Page {this.page}</div>;
+   *   }
+   * }
+   * ```
+   *
+   * @category Composition
+   */
+  static using: Compose = _compose;
+
   // ── @internal: framework bookkeeping, not part of the developer API ──────────
 
   /** Set to true by hydrate() so the framework skips calling onMount(). @internal */

package/src/decorators.ts

@@ -3,8 +3,20 @@
 // 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.
+// METHOD / GETTER decorators (@computed, @expose on a method, @renderless, @task, @on) CANNOT
+// rely on `addInitializer` either. Bun 1.3.x does not reliably run a method decorator's
+// initializers on construction: a class whose SUBCLASS declares a decorated field never runs the
+// base's method initializers at all, so a shared page base's `@expose` action silently vanished
+// from the allowlist the moment a subclass added one `@expose` field — and since the un-@exposed
+// action check is fatal, a legitimate action was then rejected at runtime. It reproduces with no
+// mixin and no framework code (a bare `class Sub extends Base` on Bun 1.3.14).
+//
+// So method/getter decorators TAG the function object itself in the decorator body — which runs
+// synchronously, with the right name, always — and the `get*` readers scan the prototype chain
+// for tagged members on first read (`_scanProto`). Registration lands on the DECLARING prototype,
+// which is what makes inheritance work through `_collect`'s existing chain walk. `addInitializer`
+// is still called as a belt-and-braces fallback: it is harmless when it fires (the registries are
+// Sets keyed by prototype) and it covers members a prototype scan cannot see.
 //
 // FIELD decorators (@expose on a field, @locked, @reactive, @modelable, @transient,
 // @validate, @url, @session) CANNOT defer to a field initializer or to `addInitializer`:
@@ -106,6 +118,72 @@ function _registerOn(map: WeakMap<object, Set<string>>, self: unknown, key: stri
   _register(map, Object.getPrototypeOf(self as object) as object, key);
 }
 
+// ── Method/getter tagging (Bun addInitializer workaround) ─────────────────────
+//
+// See the header note. A method or getter decorator marks the function object it is handed
+// (or, for @computed, the wrapper it returns); `_scanProto` later reads those marks off the
+// prototype and populates the registries. Symbols so a mark can never collide with a user
+// property, and non-enumerable so nothing serializes or copies them.
+
+/** Which registry a tagged member belongs in. `on` also carries its event name. */
+interface MemberTag {
+  exposed?: boolean;
+  renderless?: boolean;
+  task?: boolean;
+  computed?: boolean;
+  on?: string;
+}
+
+// `unique symbol` (not a plain `symbol`) so the computed-key types below resolve.
+const TAG: unique symbol = Symbol.for("zerotal.flow.memberTag");
+const SCANNED: unique symbol = Symbol.for("zerotal.flow.scanned");
+
+/** Attach/merge a tag on a decorated method or getter function. */
+function _tag(fn: unknown, patch: MemberTag): void {
+  if (typeof fn !== "function") return;
+  const target = fn as { [TAG]?: MemberTag };
+  if (!Object.prototype.hasOwnProperty.call(fn, TAG)) {
+    // Own, non-enumerable slot — an inherited tag from an overridden base method must not leak.
+    Object.defineProperty(fn, TAG, { value: {}, writable: true, configurable: true });
+  }
+  Object.assign(target[TAG] as MemberTag, patch);
+}
+
+/**
+ * Populate the method/getter registries for one prototype from the tags its own members carry.
+ * Idempotent and cheap: marked with a non-enumerable flag so it runs once per prototype.
+ */
+function _scanProto(proto: object): void {
+  if (!proto || proto === Object.prototype) return;
+  if (Object.prototype.hasOwnProperty.call(proto, SCANNED)) return;
+  Object.defineProperty(proto, SCANNED, { value: true, configurable: true });
+
+  for (const name of Object.getOwnPropertyNames(proto)) {
+    if (name === "constructor") continue;
+    const desc = Object.getOwnPropertyDescriptor(proto, name);
+    if (!desc) continue;
+    // A method lives on `value`; a @computed getter on `get`.
+    const fn: unknown = desc.value ?? desc.get;
+    if (typeof fn !== "function") continue;
+    if (!Object.prototype.hasOwnProperty.call(fn, TAG)) continue;
+    const tag = (fn as { [TAG]?: MemberTag })[TAG];
+    if (!tag) continue;
+
+    if (tag.exposed) _register(_exposedMethods, proto, name);
+    if (tag.renderless) _register(_renderlessMethods, proto, name);
+    if (tag.task) _register(_taskMethods, proto, name);
+    if (tag.computed) _register(_computedProtos, proto, name);
+    if (tag.on !== undefined) _registerMap(_onListeners, proto, tag.on, name);
+  }
+}
+
+/** Scan `startProto` and every prototype above it, so inherited members register too. */
+function _scanChain(startProto: object | null): void {
+  for (let p = startProto; p && p !== Object.prototype; p = Object.getPrototypeOf(p) as object) {
+    _scanProto(p);
+  }
+}
+
 // ── Field-decorator buffer (Bun standard-decorator workaround) ────────────────
 
 interface PendingField {
@@ -235,7 +313,9 @@ function _assertField(name: string, context: { kind: string }): void {
 }
 
 export function getComputedKeys(instance: object): Set<string> {
-  return _collect(_computedProtos, Object.getPrototypeOf(instance) as object);
+  const proto = Object.getPrototypeOf(instance) as object;
+  _scanChain(proto);
+  return _collect(_computedProtos, proto);
 }
 export function getTransientKeys(instance: object): Set<string> {
   _ensureDrained(instance);
@@ -250,13 +330,16 @@ export function getLockedProps(instance: object): Set<string> {
   return _collect(_lockedProps, Object.getPrototypeOf(instance) as object);
 }
 export function getExposedMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_exposedMethods, PageClass.prototype as object);
 }
 /** `@task` method names — streaming, cancellable long-running actions. */
 export function getTaskMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_taskMethods, PageClass.prototype as object);
 }
 export function getRenderlessMethods(PageClass: { prototype: object }): Set<string> {
+  _scanChain(PageClass.prototype as object);
   return _collect(_renderlessMethods, PageClass.prototype as object);
 }
 export function getValidateRules(instance: object): Map<string, ValidateBuilder> {
@@ -264,6 +347,7 @@ export function getValidateRules(instance: object): Map<string, ValidateBuilder>
   return _collectMap(_validateRules, Object.getPrototypeOf(instance) as object);
 }
 export function getListeners(PageClass: { prototype: object }): Map<string, string> {
+  _scanChain(PageClass.prototype as object);
   return _collectMap(_onListeners, PageClass.prototype as object);
 }
 export function getUrlProps(instance: object): Map<string, UrlOptions> {
@@ -358,7 +442,10 @@ export function computed<This, Return>(
   context.addInitializer(function (this: This) {
     _registerOn(_computedProtos, this, name);
   });
-  return _memoizeGetter(getter, name) as (this: This) => Return;
+  const memoized = _memoizeGetter(getter, name);
+  // Tag the wrapper we return — that is what lands on the prototype, not `getter`.
+  _tag(memoized, { computed: true });
+  return memoized as (this: This) => Return;
 }
 
 // ── @transient ────────────────────────────────────────────────────────────────
@@ -428,7 +515,9 @@ export function expose(_value: unknown, context: ExposeContext): void {
     _enqueueField(name, (proto) => _register(_exposedProps, proto, name));
     return;
   }
-  // Method: addInitializer is available (and reliable) on method contexts.
+  // Method: tag the function so `_scanProto` finds it on the DECLARING prototype (see header);
+  // addInitializer stays as a fallback for anything a prototype scan cannot reach.
+  _tag(_value, { exposed: true });
   context.addInitializer(function (this: unknown) {
     _registerOn(_exposedMethods, this, name);
   });
@@ -664,6 +753,7 @@ export const modelable = _fieldDecorator((proto, name) => {
  * @category Actions
  */
 export function renderless(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  _tag(_fn, { renderless: true });
   context.addInitializer(function (this: unknown) {
     _registerOn(_renderlessMethods, this, String(context.name));
   });
@@ -703,6 +793,8 @@ export function renderless(_fn: unknown, context: ClassMethodDecoratorContext):
  * @category Actions
  */
 export function task(_fn: unknown, context: ClassMethodDecoratorContext): void {
+  // `@task` implies `@expose` — it registers into the same allowlist.
+  _tag(_fn, { exposed: true, task: true });
   context.addInitializer(function (this: unknown) {
     const proto = Object.getPrototypeOf(this as object) as object;
     const name = String(context.name);
@@ -776,6 +868,8 @@ export function on(
   eventName: LooseEventName,
 ): (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.
+    _tag(_fn, { exposed: true, on: eventName });
     context.addInitializer(function (this: unknown) {
       const proto = Object.getPrototypeOf(this as object) as object;
       const name = String(context.name);

package/src/index.ts

@@ -70,9 +70,9 @@ export type {
   FlashBuilder,
   FlashOptions,
 } from "./Component.ts";
-// Compose focused feature mixins onto Component — `class extends ComponentWith(Pagination, …)`.
-export { ComponentWith } from "./mixins.ts";
-export type { Constructor, Mixin } from "./mixins.ts";
+// Mixin authoring types. Compose them onto a page with the `Component.using(...)` static —
+// `class PostsPage extends Component.using(Pagination, …)`.
+export type { Constructor, Mixin, Compose } from "./mixins.ts";
 export { Layout } from "./Layout.ts";
 export { Form, registerForm } from "./Form.ts";
 // Global client store — app-wide, client-only reactive UI state, read in JSX as
@@ -80,7 +80,7 @@ export { Form, registerForm } from "./Form.ts";
 // `FlowStore` to type it.
 export { defineStore } from "./store.ts";
 export type { FlowStore } from "./store.ts";
-// Pagination state mixin (compose with `ComponentWith(Pagination)`); `paginate`/`Paginator`
+// Pagination state mixin (compose with `Component.using(Pagination)`); `paginate`/`Paginator`
 // are the in-memory paginator.
 export { paginate, Pagination } from "./pagination.ts";
 export type { Paginator } from "./pagination.ts";
@@ -227,7 +227,7 @@ import type { PageClassWithMeta } from "./registry.ts";
 // File uploads
 export { TemporaryUploadedFile } from "./uploads/TemporaryUploadedFile.ts";
 export type { UploadRef } from "./uploads/TemporaryUploadedFile.ts";
-// File-upload management mixin (compose with `ComponentWith(FileUploads)`).
+// File-upload management mixin (compose with `Component.using(FileUploads)`).
 export { FileUploads } from "./uploads/FileUploads.ts";
 
 // Validation

package/src/mixins.ts

@@ -1,17 +1,9 @@
 // ── Component mixins ────────────────────────────────────────────────────────
 //
-// `ComponentWith(...)` composes any number of feature mixins on top of `Component`,
-// so a page can be broken into focused, reusable behaviours (pagination, file uploads,
-// sortable tables, …) that stack left-to-right instead of bloating one class — the
-// Flow counterpart of the ORM's `BaseModelWith(...)`:
-//
-//   // before — one class carrying every feature inline, base repeated per mixin
-//   class UsersPage extends FileUploads(Pagination(Component)) { … }
-//
-//   // after — flat, left-to-right, base baked in
-//   class UsersPage extends ComponentWith(Pagination, FileUploads) {
-//     async render() { … }   // the page only owns its own markup + state
-//   }
+// Mixin composition machinery for Flow. The entry point is `Component.using(...)`
+// (see Component.ts) — this module owns the types it is built from, and the fold
+// itself. Nothing here imports `Component`: the fold seeds from its receiver, so
+// this is a leaf module.
 //
 // A Component mixin is the canonical generic form below — note it extends an ABSTRACT
 // base and returns an `abstract class`, so it doesn't have to implement Component's
@@ -28,21 +20,7 @@
 //     return WithUpload;
 //   }
 //
-// Because each mixin returns `class extends Base`, Component's full surface (`flash()`,
-// `redirect()`, `validate()`, the `this.set`/`refresh`/… client magics, …) and every other
-// mixin's members flow through to the final page — fully type-checked. The shipped
-// `Pagination` mixin (see ./pagination.ts) is written exactly this way and composes here:
-// `ComponentWith(Pagination)`.
-//
-// Mixin `@expose`/`@locked` props register on the mixin's prototype, which sits in the page's
-// prototype chain — so they're discovered at runtime exactly like props declared on the page
-// itself (snapshot, reactivity, client writes, `@url` sync all work). Note: pages composed
-// with `ComponentWith(...)` render via the runtime path rather than the AOT compiler (which
-// only statically sees a page's own `extends Component` + locally-declared members) — the same
-// fallback complex pages already use; behaviour is identical, you just don't get the
-// ahead-of-time compile step for that page.
-
-import { Component } from "./Component.ts";
+// Compose them onto a page with `Component.using(FileUpload, …)`.
 
 /**
  * A class constructor. Abstract-aware (`abstract new …`) so the abstract `Component` base —
@@ -65,135 +43,127 @@ export type Mixin<TIn extends Constructor = Constructor, TOut extends Constructo
   Base: TIn,
 ) => TOut;
 
-type Base = typeof Component;
-
 /**
- * Compose one or more feature {@link Mixin}s onto {@link Component}, folding them left-to-right
- * so a page can be built from focused, reusable behaviours instead of one bloated class.
- *
- * @remarks
- * Each mixin receives the accumulated base and returns an extended class, so `Component`'s full
- * surface (`flash()`, `redirect()`, `validate()`, the client magics, …) and every mixin's
- * `@expose`/`@locked` members flow through to the final page — fully type-checked. Mixin props
- * register on the mixin prototype, which sits in the page's prototype chain, so snapshot,
- * reactivity, and client writes all work. Overloads cover 1–8 mixins; nest another
- * `ComponentWith(...)` call for more. Pages composed this way render via the runtime path rather
- * than the AOT compiler.
- *
- * @param mixins  mixin factories applied left-to-right (each takes the prior result as its base).
- * @returns a class extending `Component` with every mixin's members mixed in.
+ * The call signatures behind `Component.using(...)`.
  *
- * @example
- * ```tsx
- * // app/flow/mixins/pagination.ts
- * import { Component, expose, type Constructor } from "@zerotal/flow";
+ * Each overload threads the accumulated type through every step, so the composed class carries
+ * the base's full surface plus every mixin's members — fully type-checked. The `this: TBase`
+ * parameter is what makes the base polymorphic: `using` composes onto whatever class it is
+ * called on, not onto a hardcoded `Component`.
  *
- * export function Pagination<T extends Constructor<Component>>(Base: T) {
- *   abstract class WithPagination extends Base {
- *     @expose page = 1;
- *     @expose next() { this.page++; }
- *   }
- *   return WithPagination;
- * }
- *
- * // app/flow/UsersPage.tsx
- * class UsersPage extends ComponentWith(Pagination) {
- *   override async render() {
- *     return <div data-flow-root>Page {this.page}</div>;
- *   }
- * }
- * ```
+ * Overloads cover 1–8 mixins. There is no ceiling: the composed class carries `using` too, so
+ * `Base.using(a, b).using(c, d)` chains.
  */
-export function ComponentWith<A extends Constructor>(a: (base: Base) => A): A;
-export function ComponentWith<A extends Constructor, B extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-): B;
-export function ComponentWith<A extends Constructor, B extends Constructor, C extends Constructor>(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-): C;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
->(a: (base: Base) => A, b: (base: A) => B, c: (base: B) => C, d: (base: C) => D): D;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-): E;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-): F;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-): G;
-export function ComponentWith<
-  A extends Constructor,
-  B extends Constructor,
-  C extends Constructor,
-  D extends Constructor,
-  E extends Constructor,
-  F extends Constructor,
-  G extends Constructor,
-  H extends Constructor,
->(
-  a: (base: Base) => A,
-  b: (base: A) => B,
-  c: (base: B) => C,
-  d: (base: C) => D,
-  e: (base: D) => E,
-  f: (base: E) => F,
-  g: (base: F) => G,
-  h: (base: G) => H,
-): H;
+export interface Compose {
+  <TBase extends Constructor, A extends Constructor>(this: TBase, a: (base: TBase) => A): A;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+  ): B;
+  <TBase extends Constructor, A extends Constructor, B extends Constructor, C extends Constructor>(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+  ): C;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+  ): D;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+  ): E;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+  ): F;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+  ): G;
+  <
+    TBase extends Constructor,
+    A extends Constructor,
+    B extends Constructor,
+    C extends Constructor,
+    D extends Constructor,
+    E extends Constructor,
+    F extends Constructor,
+    G extends Constructor,
+    H extends Constructor,
+  >(
+    this: TBase,
+    a: (base: TBase) => A,
+    b: (base: A) => B,
+    c: (base: B) => C,
+    d: (base: C) => D,
+    e: (base: D) => E,
+    f: (base: E) => F,
+    g: (base: F) => G,
+    h: (base: G) => H,
+  ): H;
+}
 
-// Implementation: fold the mixins over Component, left to right. The base param is `any` so
-// each typed overload above (whose base is the narrower `typeof Component` or a prior mixin's
-// result) stays assignable to this implementation signature.
-export function ComponentWith(
+/**
+ * The fold behind {@link Compose}: apply each mixin left-to-right, seeding from `this` (the
+ * class `using` was called on). Assigned to `Component.using` — not exported publicly.
+ *
+ * @internal
+ */
+export const _compose = function (
+  this: Constructor,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- variadic mixin folder
   ...mixins: Array<(base: any) => Constructor>
 ): Constructor {
-  return mixins.reduce<Constructor>(
-    (acc, mixin) => mixin(acc),
-    Component as unknown as Constructor,
-  );
-}
+  return mixins.reduce<Constructor>((acc, mixin) => mixin(acc), this);
+} as Compose;

package/src/pagination.ts

@@ -133,7 +133,7 @@ export function paginate<T>(items: T[], page = 1, perPage = 15): Paginator<T> {
 // `previousPage`, `gotoPage`, `resetPage`), WITHOUT putting any of that on
 // the base Component.
 //
-//   class PostsPage extends ComponentWith(Pagination) {
+//   class PostsPage extends Component.using(Pagination) {
 //     @locked posts: Post[] = [];
 //     async onMount() { this.posts = await Post.all(); }
 //     async render() {
@@ -200,7 +200,7 @@ const DEFAULT_PAGE = "page";
  *
  * @example
  * ```tsx
- * class PostsPage extends ComponentWith(Pagination) {
+ * class PostsPage extends Component.using(Pagination) {
  *   @locked posts: Post[] = [];
  *   async onMount() { this.posts = await Post.all(); }
  *   async render() {

package/src/uploads/FileUploads.ts

@@ -7,7 +7,7 @@
 // This mixin adds the ergonomic server-side actions for managing those pending uploads —
 // chiefly removing a chosen file before it's stored — without bloating the base class.
 //
-//   class Avatar extends ComponentWith(FileUploads) {
+//   class Avatar extends Component.using(FileUploads) {
 //     @expose photo: TemporaryUploadedFile | null = null;
 //     @expose async save() {
 //       this.path = await this.photo?.store("avatars"); // persist permanently
@@ -48,7 +48,7 @@ type AbstractComponentCtor = abstract new (...args: any[]) => Component;
  *
  * @example
  * ```tsx
- * class Avatar extends ComponentWith(FileUploads) {
+ * class Avatar extends Component.using(FileUploads) {
  *   @expose photo: TemporaryUploadedFile | null = null;
  *   @expose path = "";
  *

package/src/uploads/TemporaryUploadedFile.ts

@@ -98,7 +98,7 @@ async function disk(name?: string): Promise<Disk> {
  *
  * @example
  * ```tsx
- * class Avatar extends ComponentWith(FileUploads) {
+ * class Avatar extends Component.using(FileUploads) {
  *   @expose photo: TemporaryUploadedFile | null = null;
  *   @expose path = "";
  *