better-supabase 0.13.0 → 0.14.0

package/dist/context-9Q23weHu.d.ts

@@ -0,0 +1,524 @@
+import { R as ClaimsMeta } from "./executor-CPyrQdjh.js";
+import { S as ResolvedModule, g as BlockScope, h as BlockMode, p as AnyBlocksConfig } from "./authorization-BuT26_sR.js";
+import { mn as EntityNoun, pn as EntityNames } from "./define-block-COpcS6aT.js";
+import { n as SubjectsConfig } from "./subjects-B6p4oAZJ.js";
+import { t as GuestAction } from "./guest-actions-1T1DeS5Y.js";
+//#region src/sql/resolved-names.d.ts
+/** One of a module's entities with the name the config gives it. */
+interface ResolvedEntity {
+  readonly key: string;
+  /** The logical table that holds it; global entities may have none. */
+  readonly table?: string;
+  readonly from: EntityNoun;
+  readonly to: EntityNoun;
+  readonly primary: boolean;
+  /** Renamed in every module (the tenant). */
+  readonly global: boolean;
+  /** `blocks.<name>.entities.<entity>.url`, with logical column placeholders. */
+  readonly url?: string;
+  /**
+   * What makes the entity a subject, or undefined when it isn't one or the
+   * config sets `subject: false`.
+   */
+  readonly subject?: ModuleEntitySubject;
+}
+/**
+ * A module's final names for one config: its entities as renamed and the
+ * renamer every name goes through (the tenant rename, then the module's own).
+ */
+interface ResolvedNames {
+  readonly module: string;
+  readonly entities: Readonly<Record<string, ResolvedEntity>>;
+  /** The tenant's noun, `organization` unless the tenant block renames it. */
+  readonly tenant: EntityNoun;
+  /** Tables, columns, functions, hooks and triggers: tenant and own entities. */
+  readonly naming: EntityNames;
+  /**
+   * Event types, payload keys, subjects, permission keys and TypeScript names:
+   * the module's own entities. The tenant rename leaves them alone, as it
+   * always has.
+   */
+  readonly entityNaming: EntityNames;
+}
+//#endregion
+//#region src/sql/scope.d.ts
+/**
+ * How a module checks who may reach a row, for the block's scope. Modules call
+ * these instead of naming the access contract (`can`, `tenant_ids_with`,
+ * `is_platform`) or the tenant module's helpers, so the same module runs per
+ * tenant, per user or in one shared space. In `tenant` scope each one renders
+ * the access contract call it replaces.
+ */
+interface ModuleScope {
+  readonly kind: BlockScope;
+  /**
+   * The type of a scope id: the tenant id type, or `uuid` (a user id) in `user`
+   * scope.
+   */
+  readonly idType: ModuleIdType;
+  /**
+   * The type of a managed table's scope column: `<idType> not null` per tenant,
+   * nullable outside it (`uuid default auth.uid()` per user).
+   */
+  column(): string;
+  /** True when the caller holds `permission` (a SQL expression) in scope `id`. */
+  can(id: string, permission: string): string;
+  /** True when `user` (a uuid expression) holds `permission` in scope `id`. */
+  canUser(user: string, id: string, permission: string): string;
+  /**
+   * PL/pgSQL that sets the scope id parameter `param` for the scope: the
+   * caller's id per user (the service role keeps what it passes), null in the
+   * shared space. Empty per tenant.
+   */
+  bind(param: string): string;
+  /**
+   * A scope id argument as an expression: as passed per tenant, the caller's id
+   * when it is null per user, null in the shared space.
+   */
+  value(param: string): string;
+  /**
+   * A set-returning call of the scope ids the caller holds `permission` in,
+   * usable as `select ...`, `x in (select ...)` and `from ... x`.
+   */
+  ids(permission: string): string;
+  /** A row policy check: `column` is a scope the caller holds `permission` in. */
+  check(column: string, permission: string): string;
+  /** `a = b` for scope ids, null-safe in `none` scope where they are null. */
+  eq(a: string, b: string): string;
+  /**
+   * `is_platform(permission)`: whether the caller is platform staff holding
+   * `permission`. `false` outside `tenant` scope without the access module.
+   */
+  platform(permission: string): string;
+  /** A set-returning call of the tenants the caller is a member of. */
+  members(): string;
+  /**
+   * True when the caller holds a guest grant for `action` on record `type`/`id`
+   * in tenant `tenant` (ADR 0070). A guest is not a member, so `can` stays
+   * false for them. `false` without the `guests` module and without a provider
+   * that answers for guests, and outside `tenant` scope.
+   */
+  guest(tenant: string, type: string, id: string, action: GuestAction): string;
+  /**
+   * True when the caller is a guest of tenant `tenant` who represents the party
+   * `type`/`id`, such as the customer an invoice is addressed to. `false` where
+   * `guest` is.
+   */
+  guestParty(tenant: string, type: string, id: string): string;
+}
+//#endregion
+//#region src/sql/context.d.ts
+/** The scope id types SQL modules render. */
+declare const MODULE_ID_TYPES: readonly ["uuid", "text", "bigint", "integer"];
+type ModuleIdType = (typeof MODULE_ID_TYPES)[number];
+declare const isModuleIdType: (value: string) => value is ModuleIdType;
+/**
+ * A Postgres type name as one of `MODULE_ID_TYPES`: case and spacing are
+ * normalised and aliases such as `int8` resolved. `undefined` for any other
+ * type, so callers refuse it instead of guessing.
+ */
+declare function moduleIdType(value: string): ModuleIdType | undefined;
+/** One logical table of a module: its default name and logical columns. */
+interface ModuleTableSpec {
+  /** Default name, in the module's schema. */
+  readonly name: string;
+  /** Logical column to default column name. */
+  readonly columns: Readonly<Record<string, string>>;
+  /**
+   * Logical columns an adopted table may lack (mapped to `null`): the module
+   * leaves out the feature that needs them.
+   */
+  readonly optional?: readonly string[];
+  /** The app may lack the whole table (`blocks.<name>.tables.<table>: null`). */
+  readonly optionalTable?: boolean;
+  readonly adoptOnlyWhenMapped?: boolean;
+  readonly lifecycle?: ModuleTableLifecycle;
+  /**
+   * Text columns an adopted table may declare with another type, such as an
+   * enum: the module writes and compares them through `ctx.cast`.
+   */
+  readonly typed?: readonly string[];
+}
+interface ModuleTableLifecycle {
+  readonly user?: string;
+  readonly tenant?: string;
+  readonly purge?: boolean;
+  readonly omit?: readonly string[];
+  readonly export?: boolean;
+  /**
+   * Columns that hold a `credential_ref`. Exports leave them out, and the
+   * organization purger revokes each ref that carries the row's tenant through
+   * the `CredentialProvider` before the purge deletes the row.
+   */
+  readonly credentials?: readonly string[];
+  /** Revoke for the row's `user` instead of the app. Default `app`. */
+  readonly credentialSubject?: "app" | "user";
+}
+/**
+ * What makes an entity a `config.subjects` entry when the block is installed.
+ * Columns are the table's logical columns; permissions are module actions.
+ */
+interface ModuleEntitySubject {
+  readonly title: string;
+  readonly deletedAt?: string;
+  readonly permissions: {
+    readonly read: string;
+    readonly write: string;
+    /**
+     * The action whose key `attachments` checks for files on the entity, in
+     * place of `attachments.upload`. Set it when the table's own write policies
+     * check more than tenant membership (doctor BS345).
+     */
+    readonly upload?: string;
+  };
+  readonly rank?: {
+    readonly column: string;
+    readonly group: string;
+  };
+  readonly search?: {
+    readonly title: string;
+    readonly body: readonly string[];
+  };
+  readonly url?: string;
+  readonly cascade?: boolean;
+}
+/**
+ * A noun the module names its tables, functions, events, permissions and hooks
+ * after (`work_item`), renamed through `blocks.<name>.entities`.
+ */
+interface ModuleEntitySpec {
+  /** The logical table that holds the entity; global entities may have none. */
+  readonly table?: string;
+  readonly singular: string;
+  /** Defaults to the English plural of `singular`. */
+  readonly plural?: string;
+  /** The entity `entities: "<noun>"` renames. */
+  readonly primary?: boolean;
+  /** Renamed in every module, not only this one (the tenant). */
+  readonly global?: boolean;
+  readonly subject?: ModuleEntitySubject;
+}
+interface ModuleNames {
+  readonly tables: Readonly<Record<string, ModuleTableSpec>>;
+  readonly entities?: Readonly<Record<string, ModuleEntitySpec>>;
+  /**
+   * The `before_*` and `after_*` hooks the module calls, so
+   * `blocks.<name>.hooks.functions` is checked.
+   */
+  readonly hooks?: readonly string[];
+  /**
+   * The `blocks.<name>.options` keys the module reads; any other key is
+   * rejected.
+   */
+  readonly options?: readonly string[];
+  /**
+   * The events the module records, typed against its block's event map
+   * (`ModuleEvents<MessagingEvents>`); `record` rejects any other type.
+   */
+  readonly events?: Readonly<Record<string, CheckedEventSpec | undefined>>;
+  /**
+   * Tables and columns the module renamed between versions. `sql upgrade`
+   * renames them on installs below `from + 1`, after the config's entity and
+   * table renames, so a declared move needs no hand-written upgrade step.
+   */
+  readonly migrations?: readonly ModuleNameMigration[];
+}
+/**
+ * One version's table and column moves. Old names are the module's default
+ * names before the move; they go through the entity renames like every other
+ * name.
+ */
+interface ModuleNameMigration {
+  /** The installed version this move upgrades from. */
+  readonly from: number;
+  readonly description: string;
+  /** The logical table, under its current key. */
+  readonly table: string;
+  /** The table's default name before the move, when the move renamed it. */
+  readonly was?: string;
+  /** Logical column to its default name before the move. */
+  readonly columns?: Readonly<Record<string, string>>;
+}
+interface CheckedEventSpec {
+  readonly subject: string;
+  readonly payload: readonly string[];
+  readonly retries?: boolean;
+}
+/** An event a module writes to the outbox, as SQL expressions. */
+interface ModuleEmit {
+  /** The event type, e.g. `organization.created`. */
+  readonly type: string;
+  /** A `jsonb` expression. */
+  readonly payload: string;
+  /** A `text` expression, e.g. `'organizations/' || new_organization`. */
+  readonly subject?: string;
+  /** The tenant id expression; it is cast to text. */
+  readonly tenant?: string;
+  /** A `text` idempotency key expression. */
+  readonly key?: string;
+}
+/**
+ * The categories module actions are audited under. An adopted log with its own
+ * names maps them through `blocks.audit.options.values.category`.
+ */
+declare const AUDIT_CATEGORIES: readonly ["membership", "access", "security", "configuration", "billing", "data", "ai", "integration", "read"];
+type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
+/** How `record` writes an action to the audit log, as SQL expressions. */
+interface ModuleAudit {
+  /** The audit category, mapped through `blocks.audit.options.values`. */
+  readonly category: AuditCategory;
+  /** What the action changed, e.g. `user` or `api_key`. */
+  readonly targetType?: string;
+  /** A `text` expression for the changed record's id. */
+  readonly recordId?: string;
+  /** A `text` expression people recognize the target by. */
+  readonly targetLabel?: string;
+  /** A `text` expression that says what happened. */
+  readonly summary?: string;
+  /** A `jsonb` expression; defaults to the event payload. */
+  readonly metadata?: string;
+  /** A `uuid` expression for the actor; defaults to the caller. */
+  readonly actor?: string;
+  /**
+   * A `uuid` expression for the support session the action belongs to. Defaults
+   * to the session in the caller's `act` claim, which wins when set.
+   */
+  readonly supportSession?: string;
+  /**
+   * A `uuid` expression for the admin acting as the user; defaults to
+   * `act.sub`.
+   */
+  readonly impersonatedBy?: string;
+  /**
+   * A `text` expression for why the admin acts as the user; defaults to
+   * `act.reason`.
+   */
+  readonly impersonationReason?: string;
+}
+/**
+ * An action a module records once: the outbox gets it as an event and the audit
+ * log as an entry, each when its module is installed.
+ */
+interface ModuleAction extends ModuleEmit {
+  /**
+   * How the action is audited, or `false` for an event that is not an audited
+   * action, such as a chat message or a run status.
+   */
+  readonly audit: ModuleAudit | false;
+}
+/**
+ * A function of a module's contract: what other modules and the TypeScript side
+ * call.
+ */
+interface ModuleContractFunction {
+  readonly name: string;
+  /** Argument types; `{id}` stands for the module's id type. */
+  readonly args: readonly string[];
+  readonly returns: string;
+}
+/** What a module's `build` reads: resolved names for one layout. */
+interface ModuleContext {
+  readonly module: string;
+  readonly mode: BlockMode;
+  readonly config: ResolvedModule;
+  /** The quoted schema of the module's functions and managed tables. */
+  readonly schema: string;
+  readonly schemaName: string;
+  readonly idType: ModuleIdType;
+  readonly claims: ClaimsMeta;
+  readonly modules: AnyBlocksConfig;
+  /** The app-wide subject registry (`config.subjects`). */
+  readonly subjects: SubjectsConfig;
+  /**
+   * The names of `config.appTables`, created in `public` after every block
+   * file, so a block can't put a trigger on one (ADR 0043).
+   */
+  readonly appTables: ReadonlySet<string>;
+  /**
+   * Who the module's rows belong to, and the checks for it: the port every
+   * tenant, user or shared-space check goes through.
+   */
+  readonly scope: ModuleScope;
+  /**
+   * The module's final names: its entities as `blocks.<name>.entities` and
+   * `blocks.tenant.entities.organization` rename them.
+   */
+  readonly resolved: ResolvedNames;
+  /** The renamer every default name goes through (`resolved.naming`). */
+  readonly naming: EntityNames;
+  /**
+   * Every configured block's entity renames as one, for names that span blocks,
+   * such as the permission keys in the default roles.
+   */
+  blockNaming(): EntityNames;
+  /**
+   * `schema.name` of a module function, quoted. The name is the default one;
+   * `blocks.<name>.entities` and `blocks.<name>.functions` rename it.
+   */
+  fn(name: string): string;
+  /** The unquoted name a module function is written under (see `fn`). */
+  fnName(name: string): string;
+  /** `blocks.<name>.functions` keys no `fn` call has asked for yet. */
+  unusedFunctions(): readonly string[];
+  /** Default name to written name, for every function `fn` renamed so far. */
+  functionRenames(): ReadonlyMap<string, string>;
+  /** `schema.table` of a logical table, quoted. */
+  table(logical: string): string;
+  /** The unquoted schema and name of a logical table. */
+  tableName(logical: string): {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** A logical column, quoted. Throws when an adopted table lacks it. */
+  col(table: string, column: string): string;
+  /** A logical column, unquoted. Throws when an adopted table lacks it. */
+  colName(table: string, column: string): string;
+  /** Whether a logical column exists (adopted tables can map it to `null`). */
+  has(table: string, column: string): boolean;
+  /**
+   * `value`, a text expression, as the type of a logical column the table spec
+   * lists in `typed`. In adopt mode the column may be an enum or another type
+   * with a text input, so the value goes through
+   * `better_supabase.as_column_type`; in managed mode it stays as it is.
+   */
+  cast(table: string, column: string, value: string): string;
+  /** Whether an optional logical table exists (it can be mapped to `null`). */
+  hasTable(table: string): boolean;
+  /** Whether the module owns `table` (managed mode). */
+  readonly manages: boolean;
+  readonly names: ModuleNames;
+  readonly installedModules: readonly string[];
+  /** The permission key for a module action, as a SQL literal. */
+  permission(action: string, fallback: string): string;
+  /** The permission key for a module action. */
+  permissionKey(action: string, fallback: string): string;
+  /** A trigger name with the module's prefix, quoted. */
+  trigger(name: string): string;
+  /** Whether `module` is installed alongside this one. */
+  installed(module: string): boolean;
+  /** The context of another module in the same layout. */
+  of(module: string): ModuleContext;
+  /** A string module option (`blocks.<name>.options`). */
+  text(name: string, fallback: string): string;
+  number(name: string, fallback: number): number;
+  flag(name: string, fallback: boolean): boolean;
+  /** A module option that is a list of strings. */
+  list(name: string, fallback: readonly string[]): readonly string[];
+  /** A declared module option as configured, for object-shaped options. */
+  option(name: string): unknown;
+  /**
+   * `options.extraColumns` (column name to SQL type), checked: names are
+   * lower-case identifiers, types are SQL types, and no name shadows one of
+   * `table`'s mapped columns or a key in `reserved`, the stable keys the
+   * module's read functions return next to them.
+   */
+  extraColumns(table: string, reserved?: readonly string[]): readonly ExtraColumn[];
+  /**
+   * PL/pgSQL that calls the app's hook function when it exists, with `[type,
+   * expression]` arguments: `if to_regprocedure(...) is not null then execute
+   * format(...) using ...; end if;`. The name comes from `to_regprocedure`
+   * rather than a literal: plpgsql_check (`supabase db lint`) checks constant
+   * dynamic SQL and fails when the hook is missing.
+   */
+  hook(name: string, args: readonly (readonly [string, string])[]): string;
+  /** The app function a hook calls, quoted, for hooks that return a value. */
+  hookTarget(name: string): string;
+  /**
+   * PL/pgSQL that writes the event to the outbox (`emit_event`) when the
+   * `outbox` module is installed and `blocks.<name>.events` isn't false;
+   * otherwise an empty string. `record` without the audit entry.
+   */
+  emit(event: ModuleEmit): string;
+  /**
+   * PL/pgSQL that writes the action to the outbox (as `emit` does) and, when it
+   * carries `audit` and the `audit` module is installed, to the audit log
+   * (`audit_event`), with `key` as the idempotency key of both. `null;` when
+   * neither applies, so it is always a valid statement.
+   */
+  record(action: ModuleAction): string;
+  /**
+   * PL/pgSQL that writes the action to the audit log only, with no outbox
+   * event, for reads that leave no change behind. `null;` without the `audit`
+   * module or when `audit` is `false`.
+   */
+  audit(action: ModuleAction): string;
+  /**
+   * PL/pgSQL that calls `notify(fields)` as the service role, which `notify()`
+   * requires, then restores the caller's claims. The function declares
+   * `v_claims text`. `null;` without the `notifications` module.
+   */
+  notify(fields: string, options?: {
+    readonly indent?: string;
+  }): string;
+  /**
+   * PL/pgSQL that enqueues a job (`enqueue_job`); `null;` without the `jobs`
+   * module. `delay` is an integer expression of seconds before it runs.
+   */
+  enqueue(queue: string, payload: string, dedupe: string, options?: {
+    readonly delay?: string;
+  }): string;
+  /**
+   * The `text[]` of a tenant's entitlements, or `fallback` without the
+   * `entitlements` module.
+   */
+  entitlements(tenant: string): string | undefined;
+  entitlements(tenant: string, fallback: string): string;
+  /**
+   * How long rows of `kind` are kept for `tenant` (SQL expressions): the
+   * data-lifecycle policy for the tenant, its plan or every tenant, else
+   * `fallback`; just `fallback` without the `data-lifecycle` module.
+   */
+  retention(kind: string, tenant: string, fallback: string): string;
+  /**
+   * Whether a legal hold covers `kind` for `tenant`; `false` without the
+   * `data-lifecycle` module.
+   */
+  held(kind: string, tenant: string): string;
+  /**
+   * The condition a purge deletes on: the row's timestamp `at` is past
+   * `retention` and no hold covers it. With data-lifecycle it first bounds `at`
+   * by the shortest policy, so the timestamp index still serves.
+   */
+  expired(kind: string, row: {
+    readonly at: string;
+    readonly tenant: string;
+    readonly fallback: string;
+  }): string;
+  /**
+   * Before when every tenant's rows of `kind` may go (a timestamptz
+   * expression), for dropping whole partitions: null under any hold on the
+   * kind, else the longest policy or `fallback`; `now() - fallback` without the
+   * `data-lifecycle` module.
+   */
+  cutoff(kind: string, fallback: string): string;
+  /**
+   * PL/pgSQL that broadcasts on a Realtime topic when `realtime.send` exists:
+   * projects without Realtime skip it.
+   */
+  broadcast(topic: string, event: string, payload: string, options?: {
+    readonly indent?: string;
+  }): string;
+  /**
+   * `coalesce(better_supabase.can(scope, id, permission), false)`; `permission`
+   * is a SQL expression. The `tenant` scope goes through `scope.can`.
+   */
+  can(scope: string, id: string, permission: string): string;
+  /**
+   * True for the service role and platform staff holding `permission` (a SQL
+   * expression); the service role only without the `access` module.
+   */
+  staff(permission: string): string;
+}
+/** A column from `options.extraColumns`. */
+interface ExtraColumn {
+  /** The column name, as reads return it. */
+  readonly name: string;
+  /** The name, quoted. */
+  readonly ident: string;
+  /** Its SQL type, such as `text not null default 'en'`. */
+  readonly type: string;
+}
+/** The contract's argument list with `{id}` resolved, as Postgres prints it. */
+declare function contractSignature(fn: ModuleContractFunction, idType: string): string;
+//#endregion
+export { ModuleAudit as a, ModuleEmit as c, ModuleNames as d, ModuleTableSpec as f, moduleIdType as h, ModuleAction as i, ModuleEntitySpec as l, isModuleIdType as m, AuditCategory as n, ModuleContext as o, contractSignature as p, MODULE_ID_TYPES as r, ModuleContractFunction as s, AUDIT_CATEGORIES as t, ModuleIdType as u };

package/dist/context-CYquqpA6.js

@@ -0,0 +1,41 @@
+import { i as userContext } from "./impersonation-CZD9AOAk.js";
+//#region src/auth/context.ts
+/** The repository context (`actor`, `claims`) for an auth state. */
+function authContext(auth) {
+	switch (auth.kind) {
+		case "user": return userContext(auth.user, auth.claims);
+		case "service": return {
+			actor: {
+				id: `service:${auth.keyName}`,
+				kind: "service",
+				role: "service_role"
+			},
+			claims: { role: "service_role" }
+		};
+		case "apiKey": return {
+			actor: auth.userId ? {
+				id: auth.userId,
+				kind: "user",
+				role: "authenticated"
+			} : {
+				id: `api-key:${auth.keyId}`,
+				kind: "service",
+				role: "authenticated"
+			},
+			claims: auth.claims,
+			...auth.organizationId ? { tenant: auth.organizationId } : {}
+		};
+		case "anon":
+		case "invalid": return {
+			actor: {
+				id: "anon",
+				kind: "anon",
+				role: "anon"
+			},
+			claims: { role: "anon" }
+		};
+		default: return auth;
+	}
+}
+//#endregion
+export { authContext as t };

package/dist/controller-CSsC9s3s.js

@@ -0,0 +1,73 @@
+import { n as whileSignedIn, t as defineController } from "./controller-BEliOBOv.js";
+import { n as sectionEventMatches } from "./sections-DjxYmpu-.js";
+import { d as findSection, f as loadSections } from "./feature-BBLdbGu7.js";
+//#region src/records/controller.ts
+/**
+* One record page's sections for the signed-in user over one realtime
+* subscription (ADR 0030): it loads them with `loadSections`, and loads a
+* section again when `topic` carries one of its events.
+*/
+function createRecordController(options) {
+	const { source, subject, sections } = options;
+	const topic = options.topic ?? null;
+	return defineController({
+		sections: void 0,
+		summary: void 0,
+		status: "closed",
+		error: void 0
+	}, (state) => {
+		const tickets = /* @__PURE__ */ new Map();
+		const loadSummary = async () => {
+			if (subject === null || options.summary === void 0) return;
+			const ticket = (tickets.get("") ?? 0) + 1;
+			tickets.set("", ticket);
+			const result = await options.summary.summary(subject, sections, options.summaryOptions);
+			if (tickets.get("") !== ticket) return;
+			state.set(result.ok ? {
+				summary: result.data,
+				error: void 0
+			} : { error: result.error });
+		};
+		const loadNamed = async (names) => {
+			if (subject === null || names.length === 0) return;
+			const mine = new Map(names.map((name) => {
+				const ticket = (tickets.get(name) ?? 0) + 1;
+				tickets.set(name, ticket);
+				return [name, ticket];
+			}));
+			const loaded = await loadSections(source, subject, names, options);
+			const current = names.filter((name) => tickets.get(name) === mine.get(name));
+			if (current.length === 0) return;
+			state.set((snapshot) => ({ sections: {
+				...snapshot.sections,
+				...Object.fromEntries(current.map((name) => [name, loaded[name]]))
+			} }));
+		};
+		const refresh = async (names) => {
+			await (names === void 0 ? Promise.all([loadNamed(sections), loadSummary()]) : loadNamed(names));
+		};
+		const stale = (event) => {
+			const matching = sections.filter((name) => (findSection(source.blocks, name)?.section.events ?? []).some((pattern) => sectionEventMatches(pattern, event)));
+			return matching.length === 0 ? sections : matching;
+		};
+		return {
+			actions: { refresh },
+			start: () => subject === null ? void 0 : whileSignedIn(options.auth, () => {
+				refresh();
+				if (topic === null) return;
+				const { leave } = options.ports.topic(topic, {
+					onMessage: (event) => {
+						Promise.all([loadNamed(stale(event)), loadSummary()]);
+					},
+					onRejoin: () => void refresh(),
+					onStatus: (status) => {
+						state.set({ status });
+					}
+				});
+				return leave;
+			})
+		};
+	});
+}
+//#endregion
+export { createRecordController as t };

package/dist/controller-DAD4hbl4.d.ts

@@ -0,0 +1,52 @@
+import { a as ClientAuth } from "./bind-Dz8y3T5T.js";
+//#region src/blocks/controller.d.ts
+/**
+ * A block's client state, framework-agnostic. `subscribe` and `getSnapshot`
+ * follow the external-store contract, so React's `useSyncExternalStore`, a Vue
+ * `shallowRef` or a Svelte store wrap it in a few lines.
+ */
+interface Controller<S, A> {
+  /**
+   * Adds a listener. The first one starts the controller's work (loads,
+   * realtime, shortcuts) and the last one to leave stops it.
+   */
+  readonly subscribe: (listener: () => void) => () => void;
+  /** The current state; the same object until it changes. */
+  readonly getSnapshot: () => S;
+  readonly actions: A;
+  /**
+   * Stops the work and drops every listener; the controller stays idle after
+   * it.
+   */
+  readonly dispose: () => void;
+}
+/** The session a controller follows: `bs.auth` from `createClient()`. */
+type AuthPort = Pick<ClientAuth, "current" | "subscribe">;
+interface ControllerState<S> {
+  readonly get: () => S;
+  /**
+   * Merges `patch` into the state; listeners hear of it only when a value
+   * changed.
+   */
+  readonly set: (patch: Partial<S> | ((current: S) => Partial<S>)) => void;
+  /**
+   * The current run: it changes when the controller starts or stops, so an
+   * answer that arrives after a restart is dropped with `run !== state.run()`.
+   */
+  readonly run: () => number;
+}
+interface ControllerParts<A> {
+  readonly actions: A;
+  /** Runs when the first listener subscribes; returns the cleanup. */
+  readonly start?: () => (() => void) | undefined;
+}
+/** Builds a controller from its initial state, its actions and its work. */
+declare function defineController<S extends object, A>(initial: S, build: (state: ControllerState<S>) => ControllerParts<A>): Controller<S, A>;
+/**
+ * Runs `effect` for the signed-in user, and again after its cleanup when
+ * another user signs in. Nothing runs while the session loads or is signed out.
+ * Returns the function that stops following the session.
+ */
+declare function whileSignedIn(auth: AuthPort, effect: (userId: string) => (() => void) | undefined): () => void;
+//#endregion
+export { defineController as a, ControllerState as i, Controller as n, whileSignedIn as o, ControllerParts as r, AuthPort as t };