@cero-base/cero 2.0.0 → 2.1.1

package/src/lib/operators.js

@@ -7,6 +7,7 @@ import { onAbort } from '@cero-base/core/utils'
 
 /**
  * @typedef {import('./refs.js').Ref} Ref
+ * @typedef {import('@cero-base/core/database').HookContext} HookContext
  * @typedef {import('../handle/index.js').CeroHandle} CeroHandle
  * @typedef {{ data: any }} SingleResult
  * @typedef {{ data: any[], total: number, size: number }} ListResult
@@ -75,17 +76,6 @@ export function del(ref, id) {
   return ref.handle.store.del(ref.name, id)
 }
 
-/**
- * Count rows on `ref`, optionally filtered.
- *
- * @param {Ref} ref
- * @param {Record<string, any>} [q]
- * @returns {Promise<{ data: number }>}
- */
-export function count(ref, q) {
-  return ref.handle.store.count(ref.name, q)
-}
-
 /**
  * Invoke an `action`-kind ref (a custom mutation declared in the schema).
  *
@@ -100,14 +90,22 @@ export function call(ref, d) {
 const WRITES = { single: ['set'], collection: ['put', 'set', 'del'] }
 
 /**
- * Intercept writes to `ref` before they commit — `fn(ctx)` runs in-path (awaited).
+ * Rule that runs before a write to `ref` lands — at apply, on every peer, inside the op's
+ * transaction. Return `false` to refuse it: the writer's own call rejects with `REFUSED`.
+ * `ctx` is `{ op, name, row, existing, id, memberId, role, get, put, set, del }`; mutate
+ * `ctx.row` to rewrite what is stored. `op` is the op as it applies, so an upsert on a
+ * collection is a `put`. The four operators on `ctx` read and write the room as it stands at
+ * this op, inside the transaction. Must be deterministic — read only `ctx`, never a clock or
+ * local state — and registered before any op applies, in the process that owns the data. The
+ * imported operators throw inside a hook; use the ones on `ctx`. Not available over RPC.
  *
  * @param {Ref} ref
- * @param {(ctx: { op: string, name: string, row: any }) => any} fn
+ * @param {(ctx: HookContext) => unknown} fn
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
 export function before(ref, fn, opts) {
+  if (ref.type) return ref.handle._hookType(before, ref, fn, opts)
   const db = ref.handle.store
   const ops = WRITES[ref.kind] || ['set']
   const offs = ops.map((op) =>
@@ -123,22 +121,24 @@ export function before(ref, fn, opts) {
 }
 
 /**
- * Subscribe to writes on `ref` — fires after each committed write, non-blocking (observe
- * only).
+ * Rule that runs after a write to `ref` lands — at apply, on every peer, inside the op's
+ * transaction. Write derived rows through `ctx.put` / `ctx.set` / `ctx.del`; a throw refuses
+ * the whole op. Same `ctx` and the same determinism and registration rules as `before`. Use
+ * `changes(ref)` instead to observe writes locally.
  *
  * @param {Ref} ref
- * @param {(ctx: { op: string, name: string, row: any }) => void} fn
+ * @param {(ctx: HookContext) => unknown} fn
  * @param {{ signal?: AbortSignal }} [opts]
  * @returns {() => void}
  */
 export function after(ref, fn, opts) {
+  if (ref.type) return ref.handle._hookType(after, ref, fn, opts)
   const db = ref.handle.store
   const ops = WRITES[ref.kind] || ['set']
-  const handler = (ctx) => ctx.name === ref.name && fn(ctx)
-  for (const op of ops) db.on(`after:${op}`, handler)
+  const offs = ops.map((op) => db.after(op, (ctx) => (ctx.name === ref.name ? fn(ctx) : undefined)))
   let stopAbort
   const off = () => {
-    ops.forEach((op) => db.off(`after:${op}`, handler))
+    offs.forEach((unsub) => unsub())
     stopAbort?.()
   }
   stopAbort = onAbort(opts?.signal, off)
@@ -333,52 +333,3 @@ export function open(ref, arg) {
 export function rotate(handle) {
   return handle.store.rotate()
 }
-
-const registry = {}
-
-function attach(handle, ns, fns) {
-  const bound = {}
-  for (const key of Object.keys(fns)) {
-    if (typeof fns[key] === 'function') bound[key] = (...args) => fns[key](handle, ...args)
-  }
-  handle[ns] = bound
-}
-
-/**
- * Put custom operators on `handle`, currying it as their first argument so
- * `handle.ns.fn(args)` calls `fn(handle, args)`.
- *
- * @param {any} handle
- * @param {Record<string, any> | string | null} arg
- * @returns {any} handle
- */
-export function bind(handle, arg) {
-  if (arg !== null && typeof arg !== 'string') {
-    for (const ns of Object.keys(arg)) attach(handle, ns, arg[ns])
-    return handle
-  }
-  const handles = handle.spec?.meta?.handles || {}
-  for (const ns of Object.keys(registry)) {
-    if (arg === null) {
-      if (!(ns in handles)) attach(handle, ns, registry[ns]) // bare root namespace
-    } else if (ns === arg) {
-      for (const k of Object.keys(registry[ns])) attach(handle, k, registry[ns][k]) // child group
-    }
-  }
-  return handle
-}
-
-/**
- * Register custom operators by scope. A bare key binds on the root handle; a key that
- * names a child-handle type binds on every handle of that type.
- *
- * @param {Record<string, any>} map
- */
-export function define(map) {
-  Object.assign(registry, map)
-}
-
-/** Test seam: clear all registered operators. */
-export function _clearDefined() {
-  for (const k of Object.keys(registry)) delete registry[k]
-}

package/src/lib/refs.js

@@ -18,11 +18,12 @@ export class Ref {
    * @param {string} kind  Ref kind: `'collection'`, `'single'`, `'action'`, or `'handle'`.
    * @param {string | null} [schema]  Fully-qualified schema id, if any.
    */
-  constructor(handle, name, kind, schema = null) {
+  constructor(handle, name, kind, schema = null, type = null) {
     this.handle = handle
     this.name = name
     this.kind = kind
     this.schema = schema
+    this.type = type
   }
 
   /**
@@ -31,8 +32,9 @@ export class Ref {
    *
    * @param {any} target
    * @param {Record<string, RefInfo>} refs
+   * @param {Record<string, any>} [handles]  The handle types, so `target.room.notes` names every room's notes.
    */
-  static attach(target, refs) {
+  static attach(target, refs, handles) {
     for (const [name, info] of Object.entries(refs || {})) {
       // a ref named like a reserved member must fail loud, not overwrite it
       if (name in target) {
@@ -40,7 +42,10 @@ export class Ref {
           `schema ref '${name}' collides with a reserved ${target.constructor?.name || 'handle'} member — rename it`
         )
       }
-      target[name] = new Ref(target, name, info.kind, info.schema)
+      const ref = (target[name] = new Ref(target, name, info.kind, info.schema))
+      for (const [sub, i] of Object.entries(handles?.[name]?.meta?.refs || {})) {
+        ref[sub] = new Ref(target, sub, i.kind, i.schema, name)
+      }
     }
   }
 }

package/src/rpc/client.js

@@ -5,23 +5,11 @@ import z32 from 'z32'
 import { decodeId } from '@cero-base/core/blobs/codec'
 
 import { Ref } from '../lib/refs.js'
-import {
-  put,
-  set,
-  get,
-  del,
-  count,
-  watch,
-  changes,
-  call,
-  open,
-  rotate,
-  bind,
-  define
-} from '../lib/operators.js'
+import { put, set, get, del, watch, changes, call, open, rotate } from '../lib/operators.js'
 import { t, schema } from '../lib/spec.js'
+import { operatorsOf, bind } from '../extensions/index.js'
 
-export { put, set, get, del, count, watch, changes, call, open, rotate, bind, define, t, schema }
+export { put, set, get, del, watch, changes, call, open, rotate, t, schema }
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCClient} BaseRPCClient
@@ -252,24 +240,6 @@ const operators = {
     await this.rpc.del({ handle: this.id, ref: name, id, local: this._local })
   },
 
-  /**
-   * Count matching rows.
-   *
-   * @param {string} name
-   * @param {Record<string, any>} [query]
-   * @returns {Promise<{ data: number }>}
-   */
-  async count(name, query) {
-    const codec = this._codec()
-    const res = await this.rpc.count({
-      handle: this.id,
-      ref: name,
-      query: codec.encodeQuery(query),
-      local: this._local
-    })
-    return { data: res.count }
-  },
-
   /**
    * Live snapshot stream. Re-emits the latest `get()` shape on every
    * underlying mutation. Destroy the stream to stop watching.
@@ -409,6 +379,16 @@ const operators = {
   async rotate() {
     const { epoch } = await this.rpc.rotate({ handle: this.id })
     return { epoch }
+  },
+
+  /**
+   * `true` ranks this handle as just updated on the server, `false` takes it off the swarm.
+   *
+   * @param {boolean} active
+   * @returns {Promise<void>}
+   */
+  async setActive(active) {
+    await this.rpc.setActive({ handle: this.id, active })
   }
 }
 
@@ -464,11 +444,13 @@ export class Client extends RPCClient {
   /**
    * @param {any} ipc   Framed IPC stream (must be writable).
    * @param {Spec} spec  Compiled cero spec (schema + rpc + handles).
+   * @param {{ operators?: Record<string, any> }} [opts]  The operators to bind, instead of the ones the spec carries.
    */
-  constructor(ipc, spec) {
+  constructor(ipc, spec, opts = {}) {
     super(ipc, spec)
     if (spec.local?.schema && !spec.local.codec) bindCodec(spec.local)
     Object.assign(this, operators)
+    this.operators = operatorsOf(spec, opts.operators)
     this.id = null
     this.deviceId = null
     this.store = this
@@ -484,10 +466,20 @@ export class Client extends RPCClient {
     this._fileToken = fileToken || ''
     this.identity = { id, toPhrase: async () => (await this.rpc.seed({})).phrase || null }
     Ref.attach(this, /** @type {Spec} */ (this.spec).meta.refs)
-    bind(this, null)
+    bind(this, null, this.operators)
     if (/** @type {Spec} */ (this.spec).meta.local?.refs) this.local = new LocalRefs(this)
   }
 
+  /** Pause networking and storage on the server. Idempotent. */
+  async suspend() {
+    await this.rpc.suspend({})
+  }
+
+  /** Resume a suspended server. Idempotent. */
+  async resume() {
+    await this.rpc.resume({})
+  }
+
   /**
    * Create a new child handle of the given type.
    *
@@ -553,7 +545,7 @@ class Handle {
     if (!this.spec.codec) bindCodec(this.spec)
     this.store = this
     Ref.attach(this, this.spec.meta.refs)
-    bind(this, this.type)
+    bind(this, this.type, parent.operators)
   }
 
   /** Underlying RPC channel borrowed from the parent. */
@@ -577,10 +569,11 @@ class Handle {
  *
  * @param {any} ipc
  * @param {object} spec
+ * @param {{ operators?: Record<string, any> }} [opts]
  * @returns {Promise<Client>}
  */
-export async function connect(ipc, spec) {
-  const client = new Client(ipc, spec)
+export async function connect(ipc, spec, opts) {
+  const client = new Client(ipc, spec, opts)
   await client.ready()
   return client
 }
@@ -591,10 +584,11 @@ export async function connect(ipc, spec) {
  *
  * @param {any} ipc    Framed IPC duplex stream.
  * @param {any} spec   Built cero spec.
+ * @param {{ operators?: Record<string, any> }} [opts]
  * @returns {Promise<Client>}
  */
-export function cero(ipc, spec) {
-  return connect(ipc, spec)
+export function cero(ipc, spec, opts) {
+  return connect(ipc, spec, opts)
 }
 cero.connect = connect
 cero.restore = restore
@@ -603,12 +597,9 @@ cero.put = put
 cero.set = set
 cero.get = get
 cero.del = del
-cero.count = count
 cero.watch = watch
 cero.changes = changes
 cero.call = call
 cero.open = open
 cero.rotate = rotate
-cero.bind = bind
-cero.define = define
 cero.schema = schema

package/src/rpc/server.js

@@ -5,7 +5,7 @@ import { CeroError } from '@cero-base/core/errors'
 import { encodeId } from '@cero-base/core/blobs/codec'
 
 import { cero, restore } from '../index.js'
-import { put, set, get, del, count, watch, changes, call } from '../lib/operators.js'
+import { put, set, get, del, watch, changes, call } from '../lib/operators.js'
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCServer} BaseRPCServer
@@ -89,7 +89,11 @@ export class Server extends RPCServer {
   /** Wire the `init` handler that lazily constructs the root cero handle. */
   _wireInit() {
     this.rpc.onInit(async () => {
-      if (this.me) throw CeroError.CONFLICT('already initialized')
+      // a reloaded UI is a new client on the same worker: it re-attaches, its old streams end
+      if (this.me) {
+        for (const handle of this._watchStreams.keys()) this._endWatches(handle)
+        return this._identity()
+      }
       this.me = await cero(this.storage, this.spec, this.opts)
       this.handles.set(this.me.id, this.me)
       await this.me.fileServer.listen()
@@ -112,7 +116,7 @@ export class Server extends RPCServer {
     })
   }
 
-  /** Register the row-level RPC handlers (put/set/get/del/count/watch/call). */
+  /** Register the row-level RPC handlers (put/set/get/del/watch/call). */
   _wireData() {
     this.rpc.onAddFile(async ({ handle, data, name, type }) => {
       const h = this._resolve(handle)
@@ -161,12 +165,6 @@ export class Server extends RPCServer {
       return {}
     })
 
-    this.rpc.onCount(async ({ handle, ref, query, local }) => {
-      const { ref: r, codec } = this._refOf(handle, ref, local)
-      const { data } = await count(r, codec.decodeQuery(query))
-      return { count: data }
-    })
-
     this.rpc.onWatch((stream) => {
       const { handle, ref, query, local } = stream.data
       let r, codec, live
@@ -280,6 +278,21 @@ export class Server extends RPCServer {
       return { epoch }
     })
 
+    this.rpc.onSetActive(({ handle, active }) => {
+      this._resolve(handle).setActive(active)
+      return {}
+    })
+
+    this.rpc.onSuspend(async () => {
+      await this.me.suspend()
+      return {}
+    })
+
+    this.rpc.onResume(async () => {
+      await this.me.resume()
+      return {}
+    })
+
     this.rpc.onJoin(async ({ parent, ref, invite }) => {
       if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
       const child = await this.me._join(invite, ref)

package/types/build/index.d.ts

@@ -8,6 +8,14 @@ export type BuildOpts = {
      * Namespace prefix for emitted schema ids. Defaults to `'cero'`.
      */
     ns?: string;
+    /**
+     * The extensions to fold in. A module specifier, relative to `specDir`, is imported here for its `extensions` export and written into the spec, so every process runs the same list. A list is folded in only. The bundled two by default, `[]` for none.
+     */
+    extensions?: string | import('../extensions/index.js').Extension[];
+    /**
+     * A module specifier, relative to `specDir`, written into the spec for its `operators` export, so every process binds the same map.
+     */
+    operators?: string;
 };
 /**
  * @typedef {import('@cero-base/core/schema').Schema} Schema
@@ -16,6 +24,8 @@ export type BuildOpts = {
  *
  * @typedef {object} BuildOpts
  * @property {string} [ns]  Namespace prefix for emitted schema ids. Defaults to `'cero'`.
+ * @property {string | import('../extensions/index.js').Extension[]} [extensions]  The extensions to fold in. A module specifier, relative to `specDir`, is imported here for its `extensions` export and written into the spec, so every process runs the same list. A list is folded in only. The bundled two by default, `[]` for none.
+ * @property {string} [operators]  A module specifier, relative to `specDir`, written into the spec for its `operators` export, so every process binds the same map.
  */
 /**
  * Compile a cero schema into wire-level artifacts and write them to disk.
@@ -25,4 +35,4 @@ export type BuildOpts = {
  * @param {BuildOpts} [opts]
  * @returns {Promise<void>}
  */
-export declare function build(specDir: string, schema: SchemaInput, { ns, extensions }?: BuildOpts): Promise<void>;
+export declare function build(specDir: string, schema: SchemaInput, { ns, extensions, operators }?: BuildOpts): Promise<void>;

package/types/build/schemas.d.ts

@@ -151,6 +151,10 @@ export declare const rpc: {
     'req-handle': {
         handle: import("@cero-base/core").Prim;
     };
+    'req-set-active': {
+        handle: import("@cero-base/core").Prim;
+        active: import("@cero-base/core").Prim;
+    };
     'res-data': {
         data: import("@cero-base/core").Prim;
     };
@@ -163,9 +167,6 @@ export declare const rpc: {
         changes: import("@cero-base/core").Prim;
         reset: import("@cero-base/core").Prim;
     };
-    'res-count': {
-        count: import("@cero-base/core").Prim;
-    };
     'res-invite': {
         invite: import("@cero-base/core").Prim;
     };

package/types/extensions/handle-sync.d.ts

@@ -8,7 +8,6 @@ export declare function handleSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
-    bundled: boolean;
     schema: {
         handles: {
             kind: 'extend';

package/types/extensions/index.d.ts

@@ -1,8 +1,63 @@
+import { t, schema } from '../lib/spec.js';
+import * as operators from '../lib/operators.js';
 export * from './profile-sync.js';
 export * from './handle-sync.js';
-export declare const registry: ({
+export { t, schema };
+export declare const put: typeof operators.put, set: typeof operators.set, get: typeof operators.get, del: typeof operators.del, watch: typeof operators.watch, changes: typeof operators.changes, call: typeof operators.call, open: typeof operators.open, rotate: typeof operators.rotate, before: typeof operators.before, after: typeof operators.after;
+export declare const cero: {
+    t: {
+        string: import("@cero-base/core").Prim;
+        uint: import("@cero-base/core").Prim;
+        int: import("@cero-base/core").Prim;
+        bool: import("@cero-base/core").Prim;
+        bytes: import("@cero-base/core").Prim;
+        json: import("@cero-base/core").Prim;
+        fixed32: import("@cero-base/core").Prim;
+        fixed64: import("@cero-base/core").Prim;
+        file: import("@cero-base/core").Prim;
+        required: (marker: import("@cero-base/core").Prim) => import("@cero-base/core").Prim;
+        single(fields: Record<string, import("@cero-base/core").Prim>): import("@cero-base/core").TypeDef;
+        collection(fields: Record<string, import("@cero-base/core").Prim>, opts?: {
+            indexes?: Record<string, string[]>;
+            own?: boolean;
+        }): import("@cero-base/core").TypeDef;
+        action(fields: Record<string, import("@cero-base/core").Prim>): import("@cero-base/core").TypeDef;
+        extend(fields: Record<string, import("@cero-base/core").Prim>): {
+            kind: 'extend';
+            fields: Record<string, import("@cero-base/core").Prim>;
+        };
+    };
+    schema: typeof schema;
+    put: typeof operators.put;
+    set: typeof operators.set;
+    get: typeof operators.get;
+    del: typeof operators.del;
+    watch: typeof operators.watch;
+    changes: typeof operators.changes;
+    call: typeof operators.call;
+    open: typeof operators.open;
+    rotate: typeof operators.rotate;
+    before: typeof operators.before;
+    after: typeof operators.after;
+};
+export type Extension = {
+    /**
+     * Refs to add, or `t.extend` on a builtin, nested by handle type like the app schema.
+     */
+    schema?: Record<string, any>;
+    /**
+     * Runs once the root is ready; a returned function runs on close.
+     */
+    setup?: (me: any) => any;
+};
+/**
+ * @typedef {object} Extension
+ * @property {Record<string, any>} [schema]  Refs to add, or `t.extend` on a builtin, nested by handle type like the app schema.
+ * @property {(me: any) => any} [setup]      Runs once the root is ready; a returned function runs on close.
+ */
+/** The two every app gets unless its build names a list. */
+export declare const bundled: ({
     name: string;
-    bundled: boolean;
     schema: {
         profile: import("@cero-base/core").TypeDef;
         members: {
@@ -13,7 +68,6 @@ export declare const registry: ({
     setup(me: any): void;
 } | {
     name: string;
-    bundled: boolean;
     schema: {
         handles: {
             kind: 'extend';
@@ -22,3 +76,29 @@ export declare const registry: ({
     };
     setup(me: any): void;
 })[];
+/**
+ * The extensions a spec carries, else the bundled two. A bare function is `{ setup }`.
+ *
+ * @param {any} spec
+ * @param {Array<any>} [override]
+ * @returns {Extension[]}
+ */
+export declare function extensionsOf(spec: any, override?: Array<any>): Extension[];
+/**
+ * The operators a spec carries: functions taking the handle first, keyed by namespace, a
+ * key naming a handle type holding that type's namespaces.
+ *
+ * @param {any} spec
+ * @param {Record<string, any>} [override]
+ * @returns {Record<string, any>}
+ */
+export declare function operatorsOf(spec: any, override?: Record<string, any>): Record<string, any>;
+/**
+ * Put the operators for `handle` on it: the root when `type` is null, else a child of `type`.
+ *
+ * @param {any} handle
+ * @param {string | null} type
+ * @param {Record<string, any>} operators
+ * @returns {any} handle
+ */
+export declare function bind(handle: any, type: string | null, operators: Record<string, any>): any;

package/types/extensions/profile-sync.d.ts

@@ -7,7 +7,6 @@ export declare function profileSync({ fields }?: {
     fields?: Record<string, any>;
 }): {
     name: string;
-    bundled: boolean;
     schema: {
         profile: import("@cero-base/core").TypeDef;
         members: {

package/types/handle/index.d.ts

@@ -74,10 +74,6 @@ export type HandleOpts = {
      * Writer keypair.
      */
     keyPair?: KeyPair;
-    /**
-     * Join discovery server-only; flip later with `setActive`.
-     */
-    passive?: boolean;
     /**
      * When `false`, skips creating a `Pairing` session.
      */
@@ -148,7 +144,6 @@ export type CeroHandle = Handle & Record<string, import('../lib/refs.js').Ref>;
  * @property {Array<{ epoch: number, entropy: Uint8Array }>} [epochs]  Rotation epochs delivered at join.
  * @property {string} [namespace]              Corestore namespace.
  * @property {KeyPair} [keyPair]               Writer keypair.
- * @property {boolean} [passive]               Join discovery server-only; flip later with `setActive`.
  * @property {boolean} [pair]                  When `false`, skips creating a `Pairing` session.
  *
  * @typedef {object} CreateChildOpts
@@ -197,8 +192,11 @@ export declare class Handle extends ReadyResource {
     _discovery: any;
     _dir: string;
     _opts: any;
+    extensions: any;
+    operators: any;
     _onerror: any;
     children: Set<any>;
+    _typeHooks: Set<any>;
     _loading: Map<any, any>;
     _joining: Map<any, any>;
     _coreKeys: Map<any, any>;
@@ -211,7 +209,7 @@ export declare class Handle extends ReadyResource {
     pair: Pairing;
     _wantsPair: boolean;
     _ac: AbortController;
-    _invitesSync: () => Promise<void>;
+    _invitesSync: (touched: any) => void;
     /** @param {HandleOpts} [opts] */
     constructor(opts?: HandleOpts);
     /**
@@ -235,6 +233,8 @@ export declare class Handle extends ReadyResource {
      * @returns {Blobs}
      */
     get blobs(): Blobs;
+    /** The handle type of a child, null on the root. */
+    get type(): any;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */
@@ -294,14 +294,12 @@ export declare class Handle extends ReadyResource {
      */
     claim(): Promise<void>;
     /**
-     * Flip this handle's swarm announce mode — `setActive(false)` demotes an idle/background
-     * room to server-only (still reachable, stops searching); `setActive(true)` promotes it
-     * back on focus.
+     * `true` ranks this handle as just touched, `false` takes it out of the swarm until the
+     * next update lands in it.
      *
      * @param {boolean} active
-     * @returns {Promise<void>}
      */
-    setActive(active: boolean): Promise<void>;
+    setActive(active: boolean): void;
     /**
      * Mint a pairing invite for this handle.
      *
@@ -415,6 +413,8 @@ export declare class Handle extends ReadyResource {
     _reopen(type: string, id: string, opts: any): Promise<Handle>;
     _suspend(): Promise<void>;
     _resume(): Promise<void>;
+    _adopt(child: any, info: any): void;
+    _hookType(op: any, ref: any, fn: any, opts: any): () => void;
     /**
      * @param {Handle} child
      * @param {{ role?: string }} [opts]