@zerotal/flow 1.0.4 → 1.3.0

package/src/compiler/transform.ts

@@ -448,14 +448,39 @@ interface MemberInfo {
   locked: Set<string>; // @locked only — readable from client, not writable
   computed: Set<string>; // @computed getters — derived, NOT in the snapshot
   readable: Set<string>; // exposed ∪ locked — any prop in the snapshot (client-reactive)
+  /** Every method declared on this class, decorated or not — see `_assertActionExposed`. */
+  declaredMethods: Set<string>;
+  /**
+   * Methods the client may call. `@expose` is the usual one, but `@task` and `@on` both
+   * register into the same allowlist (`_exposedMethods`) — a `@task` streams field writes
+   * and is dispatched exactly like any other action. Checking only for `@expose` rejected
+   * perfectly good pages.
+   */
+  callableMethods: Set<string>;
 }
 
+/** Decorators that put a method in the client-callable allowlist. */
+const ACTION_DECORATORS = new Set(["expose", "task", "on"]);
+
 /** Collect @expose, @locked, and @computed decorated members from the Component class AST. */
 function _getMemberInfo(cls: ts.ClassDeclaration): MemberInfo {
   const exposed = new Set<string>();
   const locked = new Set<string>();
   const computed = new Set<string>();
+  const declaredMethods = new Set<string>();
+  const callableMethods = new Set<string>();
   for (const member of cls.members) {
+    if (ts.isMethodDeclaration(member) && ts.isIdentifier(member.name)) {
+      declaredMethods.add(member.name.text);
+      for (const m of member.modifiers ?? []) {
+        if (!ts.isDecorator(m)) continue;
+        // `@on("evt")` is a call; `@expose` is a bare identifier.
+        const e = ts.isCallExpression(m.expression) ? m.expression.expression : m.expression;
+        if (ts.isIdentifier(e) && ACTION_DECORATORS.has(e.text)) {
+          callableMethods.add(member.name.text);
+        }
+      }
+    }
     // @computed sits on a getter (GetAccessorDeclaration); @expose/@locked on fields/methods.
     if (
       !ts.isPropertyDeclaration(member) &&
@@ -475,7 +500,55 @@ function _getMemberInfo(cls: ts.ClassDeclaration): MemberInfo {
     if (has("locked")) locked.add(name);
     if (has("computed")) computed.add(name);
   }
-  return { exposed, locked, computed, readable: new Set([...exposed, ...locked]) };
+  return {
+    exposed,
+    locked,
+    computed,
+    readable: new Set([...exposed, ...locked]),
+    declaredMethods,
+    callableMethods,
+  };
+}
+
+/**
+ * Reject `onClick={this.method}` when `method` is declared on the page but not `@expose`d.
+ *
+ * `getAllowedMethods()` is `getExposedMethods()`, so an undecorated method is simply absent
+ * from the allowlist. Everything else about the page passes — `tsc` is clean, the compiler
+ * emits `flow:click="submit"`, the button renders enabled — and the click sends a frame the
+ * server refuses, reporting it *only* over the WebSocket to `console.error`:
+ *
+ *     [Flow] Server error on …: Method "submit" is not allowed
+ *
+ * Nothing reaches the server log, nothing throws, the page does not change. To a developer,
+ * and to every test that is not a real browser with the console open, the button simply does
+ * nothing — indistinguishable from the binding bugs, so the instinct is to go hunting for one.
+ *
+ * The member table needed to catch this is already built, so catch it here.
+ *
+ * Only fires for a method *declared on this class*: an inherited handler (a base-class action,
+ * a mixin) is invisible to this AST and must not be second-guessed.
+ */
+function _assertActionExposed(
+  method: string,
+  members: MemberInfo,
+  filename: string,
+  node: ts.Node,
+): void {
+  if (!members.declaredMethods.has(method)) return; // inherited or a magic — not ours to judge
+  if (members.callableMethods.has(method)) return;
+  if (CLIENT_CALLBACK_MAGICS.has(method) || CLIENT_MAGICS.has(method)) return;
+
+  const sf = node.getSourceFile();
+  const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+  throw new FlowValidationError(
+    `[Flow] \`${method}\` is used as a server action but is not @expose'd.\n` +
+      `  ${_at(filename, line + 1, character + 1)}\n` +
+      `      → Add @expose to ${method}() (or @task / @on, which also make it callable). ` +
+      `Without it the method is not in the action ` +
+      `allowlist, so the click sends a frame the server refuses — and the refusal is ` +
+      `reported only to the browser console, which makes the button look inert.`,
+  );
 }
 
 // ── this.xxx reference extraction (read vs write) ─────────────────────────────
@@ -685,6 +758,18 @@ function _validateFlowCallbacks(sf: ts.SourceFile, members: MemberInfo, filename
         // its this.xxx refs must be @expose (writes) / @expose|@locked (reads).
         _validateArrowRefs(expr, members, filename);
       }
+
+      // onClick={this.method} / onSubmit={flow(this.method)} — the method must be
+      // @expose'd or it is not in the action allowlist. Checked here, in the pass that
+      // runs unconditionally and whose errors are fatal, rather than during transform:
+      // a transform error is caught and downgraded to a runtime fallback, which would
+      // leave the page rendering and the button still silently dead.
+      if (attrName.startsWith("on") || attrName === "submit") {
+        const ref = _isThisProp(expr)
+          ? (expr as ts.PropertyAccessExpression)
+          : _extractFlowProp(expr);
+        if (ref) _assertActionExposed(ref.name.text, members, filename, ref);
+      }
     }
     ts.forEachChild(node, scan);
   }
@@ -1671,7 +1756,8 @@ function _compileRenderMethod(
         const event = eventName;
         // onClick={this.method} — server action (named method reference).
         if (_isThisProp(expr)) {
-          emitStatic(` flow:${event}="${(expr as ts.PropertyAccessExpression).name.text}"`);
+          const method = (expr as ts.PropertyAccessExpression).name.text;
+          emitStatic(` flow:${event}="${method}"`);
           continue;
         }
         // onClick={(e) => this.x = 0} — bare arrow → client expression, emitted verbatim
@@ -1680,6 +1766,20 @@ function _compileRenderMethod(
         // key off it). The <For> path below is the one exception — a loop handler must be an
         // Alpine `@event`, because the loop variable only exists in Alpine's x-for scope.
         if (ts.isArrowFunction(expr)) {
+          // `() => this.method(row.id)` — a server action that wants an argument. The
+          // arrow itself cannot ship: it would be emitted verbatim and `row` does not
+          // exist in the browser. But this render function DOES have `row` in scope at
+          // request time, so emit the action by name and serialise the arguments beside
+          // it as data-args, which the bridge already reads and forwards. Matches what
+          // the runtime renderer achieves by invoking the arrow with a recorder.
+          const argCall = _asServerActionCall(expr, members);
+          if (argCall) {
+            emitStatic(` flow:${event}="${argCall.method}"`);
+            emitStatic(` data-args="`);
+            emitDynamic(`__escAttr(JSON.stringify([${argCall.argsSrc}]))`);
+            emitStatic(`"`);
+            continue;
+          }
           if (_cspSafe) {
             // CSP-safe: emit the bare expression body (no arrow wrapper). An event
             // param or a block body has no CSP-safe inline form → compile error.
@@ -1695,11 +1795,13 @@ function _compileRenderMethod(
                   `  Use a single expression or an @expose action.\n  File: ${filename}`,
               );
             }
+            _assertClientExprScope(expr, members, filename);
             const body = _rewriteClientExpr(expr.body.getText());
             _assertCspExpr(body, filename);
             emitStatic(` flow:${event}="${_escAttr(body)}"`);
             continue;
           }
+          _assertClientExprScope(expr, members, filename);
           const src = _rewriteClientExpr(expr.getText());
           emitStatic(` flow:${event}="${_escAttr(src)}"`);
           continue;
@@ -2047,9 +2149,246 @@ function _clientMagicSrc(expr: ts.Expression, members: MemberInfo, filename: str
       );
     }
   }
+  // Same verbatim-emission hazard as an arrow handler: this expression re-evaluates in
+  // the browser, so a captured server-side name would silently evaluate to undefined.
+  _assertClientExprScope(expr, members, filename);
   return _rewriteClientExpr(expr.getText());
 }
 
+/**
+ * Recognise `() => this.method(a, b)` — a no-parameter arrow whose whole body is one
+ * call to a component action with arguments — and return the pieces needed to emit it
+ * as `flow:<event>="method"` + `data-args`.
+ *
+ * Returns null (leaving the caller on the verbatim client-expression path) when:
+ *  - the arrow takes parameters (it wants the DOM event; that's genuinely client-side);
+ *  - the body isn't a single call, or isn't a call to `this.something`;
+ *  - the callee isn't an @expose action (a client magic like `this.refresh()` must stay
+ *    a client expression);
+ *  - **any argument reads `this`** — `this.count + 1` must re-evaluate on the client
+ *    against live reactive state, not be frozen into the markup at render time.
+ */
+function _asServerActionCall(
+  arrow: ts.ArrowFunction,
+  members: MemberInfo,
+): { method: string; argsSrc: string } | null {
+  if (arrow.parameters.length > 0) return null;
+
+  const body = ts.isBlock(arrow.body)
+    ? arrow.body.statements.length === 1 && ts.isExpressionStatement(arrow.body.statements[0]!)
+      ? (arrow.body.statements[0] as ts.ExpressionStatement).expression
+      : null
+    : arrow.body;
+  if (!body || !ts.isCallExpression(body)) return null;
+  if (!ts.isPropertyAccessExpression(body.expression)) return null;
+  if (body.expression.expression.kind !== ts.SyntaxKind.ThisKeyword) return null;
+
+  const method = body.expression.name.text;
+  if (CLIENT_CALLBACK_MAGICS.has(method) || CLIENT_MAGICS.has(method)) return null;
+  // Actions are @expose methods, so `exposed` is the whole allowlist.
+  if (!members.exposed.has(method)) return null;
+  if (body.arguments.length === 0) return null; // no args → plain flow:click="method"
+
+  for (const arg of body.arguments) {
+    if (_referencesThis(arg)) return null;
+  }
+
+  return { method, argsSrc: body.arguments.map((a) => a.getText()).join(", ") };
+}
+
+/** True when `node` reads `this` anywhere (so it must stay a live client expression). */
+function _referencesThis(node: ts.Node): boolean {
+  if (node.kind === ts.SyntaxKind.ThisKeyword) return true;
+  let found = false;
+  ts.forEachChild(node, (child) => {
+    if (!found && _referencesThis(child)) found = true;
+  });
+  return found;
+}
+
+// ── Client-expression scope validation ────────────────────────────────────────
+
+/**
+ * Names a client expression may reference besides `$flow`, its own parameters, and
+ * its own locals: Alpine's magics (the expression is evaluated by Alpine) and the
+ * browser globals it is reasonable to reach for inline.
+ */
+const CLIENT_EXPR_GLOBALS = new Set([
+  // Alpine magics
+  "$el",
+  "$event",
+  "$refs",
+  "$store",
+  "$dispatch",
+  "$watch",
+  "$nextTick",
+  "$id",
+  "$root",
+  "$data",
+  "$flow",
+  // Language / literals
+  "undefined",
+  "NaN",
+  "Infinity",
+  "globalThis",
+  "arguments",
+  // Standard built-ins
+  "Object",
+  "Array",
+  "String",
+  "Number",
+  "Boolean",
+  "Math",
+  "JSON",
+  "Date",
+  "RegExp",
+  "Map",
+  "Set",
+  "Promise",
+  "Error",
+  "Symbol",
+  "BigInt",
+  "Intl",
+  "parseInt",
+  "parseFloat",
+  "isNaN",
+  "isFinite",
+  "encodeURIComponent",
+  "decodeURIComponent",
+  "encodeURI",
+  "decodeURI",
+  "structuredClone",
+  // Browser
+  "window",
+  "document",
+  "console",
+  "navigator",
+  "location",
+  "history",
+  "localStorage",
+  "sessionStorage",
+  "fetch",
+  "URL",
+  "URLSearchParams",
+  "FormData",
+  "Event",
+  "CustomEvent",
+  "alert",
+  "confirm",
+  "prompt",
+  "setTimeout",
+  "clearTimeout",
+  "setInterval",
+  "clearInterval",
+  "requestAnimationFrame",
+  "cancelAnimationFrame",
+  "matchMedia",
+  "getComputedStyle",
+]);
+
+/** Collect every name a binding pattern introduces (`{a, b: [c]}`, `...rest`). */
+function _collectBoundNames(name: ts.BindingName, into: Set<string>): void {
+  if (ts.isIdentifier(name)) {
+    into.add(name.text);
+    return;
+  }
+  for (const element of name.elements) {
+    if (ts.isOmittedExpression(element)) continue;
+    _collectBoundNames(element.name, into);
+  }
+}
+
+/**
+ * Reject a client expression that references a name the browser will not have.
+ *
+ * Client expressions are emitted as source text with `this.` rewritten to `$flow.`;
+ * every other identifier is emitted verbatim. So a handler that closes over an
+ * enclosing scope — the loop variable in
+ * `{items.map((item) => <button onClick={() => this.select(item.id)}>)}` — compiles
+ * to `$flow.select(item.id)`, where `item` does not exist. At runtime that throws a
+ * ReferenceError inside the bridge's evaluator, which logs to the browser console
+ * and returns: the click does nothing, the server never hears about it, and the page
+ * looks perfect. Catching it here turns a silent dead button into a build error that
+ * names the identifier.
+ *
+ * Server actions that need a row id take arguments instead — `onClick={this.remove}`
+ * with `data-args={JSON.stringify([row.id])}`.
+ */
+function _assertClientExprScope(expr: ts.Expression, members: MemberInfo, filename: string): void {
+  // Names bound *within* the expression (arrow params, block locals, catch bindings).
+  const scoped = new Set<string>();
+
+  const collectScope = (node: ts.Node): void => {
+    if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+      for (const param of node.parameters) _collectBoundNames(param.name, scoped);
+    } else if (ts.isVariableDeclaration(node)) {
+      _collectBoundNames(node.name, scoped);
+    } else if (ts.isCatchClause(node) && node.variableDeclaration) {
+      _collectBoundNames(node.variableDeclaration.name, scoped);
+    }
+    ts.forEachChild(node, collectScope);
+  };
+  collectScope(expr);
+
+  const check = (node: ts.Node): void => {
+    // `a.b` — only `a` is a free identifier; `b` is a property name.
+    if (ts.isPropertyAccessExpression(node)) {
+      check(node.expression);
+      return;
+    }
+    // `{ key: value }` — `key` is not a reference.
+    if (ts.isPropertyAssignment(node)) {
+      check(node.initializer);
+      return;
+    }
+    if (ts.isShorthandPropertyAssignment(node)) {
+      // `{ x }` — `x` IS a reference.
+      _checkIdentifier(node.name, scoped, members, filename, expr);
+      return;
+    }
+    if (ts.isIdentifier(node)) {
+      _checkIdentifier(node, scoped, members, filename, expr);
+      return;
+    }
+    ts.forEachChild(node, check);
+  };
+  // Enter through `check`, not forEachChild: when the whole expression IS a property
+  // access (`$flow.store.ui.open`), forEachChild would hand us its trailing name as a
+  // bare identifier and we would reject the root of the chain's own property.
+  check(expr);
+}
+
+function _checkIdentifier(
+  id: ts.Identifier,
+  scoped: Set<string>,
+  members: MemberInfo,
+  filename: string,
+  expr: ts.Expression,
+): void {
+  const name = id.text;
+  if (scoped.has(name)) return;
+  if (CLIENT_EXPR_GLOBALS.has(name)) return;
+  if (name.startsWith("$")) return; // an Alpine plugin magic we don't know about
+
+  const sf = id.getSourceFile();
+  const { line, character } = sf.getLineAndCharacterOfPosition(id.getStart(sf));
+
+  // A member of the component is the most likely intent, and has a precise fix.
+  const isMember = members.readable.has(name) || members.exposed.has(name);
+  const hint = isMember
+    ? `Did you mean this.${name}? A bare \`${name}\` is not in scope in the browser.`
+    : `\`${name}\` comes from an enclosing server-side scope, and client expressions ` +
+      `are emitted verbatim — it will not exist in the browser.\n` +
+      `      To pass a value to a server action, use data-args:\n` +
+      `        <button onClick={this.method} data-args={JSON.stringify([${name}])}>`;
+
+  throw new FlowValidationError(
+    `[Flow] client expression references \`${name}\`, which will be undefined in the browser.\n` +
+      `  ${_at(filename, line + 1, character + 1)}  in \`${_snippet(expr, 60)}\`\n` +
+      `      → ${hint}`,
+  );
+}
+
 function _isComponent(tag: string): boolean {
   const c = tag.charCodeAt(0);
   return c >= 65 && c <= 90; // A–Z

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