@powerhousedao/reactor-browser 6.2.2-dev.27 → 6.2.2-dev.29

package/dist/attachment-service-BbtWv6CL.d.ts

@@ -0,0 +1,965 @@
+import { a as PHGlobal$1, b as IPackagesListener, ct as PromiseWithState, d as UsePHGlobalValue$1, ot as IDocumentCache, rt as IReactorBrowserClient$1, st as PromiseState, u as SetPHGlobalValue$1, v as IPackageListerUnsubscribe, x as PackageManagerInstallResult, y as IPackageManager } from "./global-C8gV1GYv.js";
+import { t as PGlite } from "./pglite-CntadC_p-BtEalg1H.js";
+import { D as Scalars, E as PropagationMode$1, O as SdkFunctionWrapper, S as GetDocumentQuery, T as PhDocumentFieldsFragment, c as ReactorGraphQLClient, k as ViewFilterInput, x as GetDocumentOperationsQuery, y as DocumentChangesSubscription } from "./types-jEQ5crx9.js";
+import { Action, DocumentModelLib, DocumentModelModule, Operation, PHDocument } from "document-model";
+import { Action as Action$1, DocumentOperations, ISigner, PHBaseState, PHDocument as PHDocument$1, PHDocumentHeader } from "@powerhousedao/shared/document-model";
+import * as _powerhousedao_reactor0 from "@powerhousedao/reactor";
+import { Database, DocumentChangeEvent, DocumentModelSource, IDocumentModelRegistry, ISyncManager, OperationFilter, PagedResults, PagingOptions, PropagationMode, SearchFilter, ViewFilter } from "@powerhousedao/reactor";
+import { ReactNode } from "react";
+import { GraphQLClient, Variables } from "graphql-request";
+import * as graphql from "graphql";
+import { DocumentNode } from "graphql";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
+import { IAttachmentService } from "@powerhousedao/reactor-attachments/client";
+import { Kysely } from "kysely";
+import { AddPHGlobalEventHandler, BrowserReactorClientModule, IReactorBrowserClient, SetPHGlobalValue, UsePHGlobalValue, WorkerReactorClientModule } from "@powerhousedao/reactor-browser";
+import { RegistryPackageSource } from "@powerhousedao/shared";
+
+//#region src/document-cache.d.ts
+declare function addPromiseState<T>(promise: Promise<T>): PromiseWithState<T>;
+declare function readPromiseState<T>(promise: Promise<T> | PromiseWithState<T>): PromiseState<T>;
+/**
+ * Document cache implementation that uses the new ReactorClient API.
+ *
+ * This cache subscribes to document change events via IReactorBrowserClient.subscribe()
+ * and automatically updates the cache when documents are created, updated, or deleted.
+ */
+declare class DocumentCache implements IDocumentCache {
+  private client;
+  private documents;
+  private batchPromises;
+  private listeners;
+  private unsubscribe;
+  constructor(client: IReactorBrowserClient$1);
+  private handleDocumentChange;
+  private handleDocumentDeleted;
+  private handleDocumentUpdated;
+  private invalidateBatchesContaining;
+  get(id: string, refetch?: boolean): Promise<PHDocument$1>;
+  getBatch(ids: string[]): Promise<PHDocument$1[]>;
+  subscribe(id: string | string[], callback: () => void): () => void;
+  /**
+   * Disposes of the cache and unsubscribes from document change events.
+   */
+  dispose(): void;
+}
+//#endregion
+//#region src/remote-controller/types.d.ts
+type RemoteControllerGraphQLClient = Pick<ReactorGraphQLClient, "GetDocument" | "GetDocumentWithOperations" | "GetDocumentOperations" | "MutateDocument" | "CreateDocument" | "CreateEmptyDocument" | "DeleteDocument" | "BatchGetDocumentOperations" | "BatchGetDocumentWithOperations">;
+type RemoteDocumentData = PhDocumentFieldsFragment;
+type RemoteOperation = GetDocumentOperationsQuery["documentOperations"]["items"][number];
+type RemoteOperationResultPage = GetDocumentOperationsQuery["documentOperations"];
+/**
+ * Options for creating a RemoteDocumentController.
+ */
+type RemoteControllerOptions = {
+  client: RemoteControllerGraphQLClient; /** Remote document id. Omit for new documents. */
+  documentId?: string; /** "batch" requires explicit push(), "streaming" auto-pushes after actions. Defaults to "batch" */
+  mode?: "batch" | "streaming"; /** Optional signer for action signing. */
+  signer?: ISigner; /** Branch name, defaults to "main". */
+  branch?: string; /** Parent document identifier for creating new documents. */
+  parentIdentifier?: string; /** Conflict resolution strategy when remote has new operations. Default: no check (current behavior). */
+  onConflict?: ConflictStrategy; /** Called when a streaming-mode push fails. If not provided, errors are silently swallowed. */
+  onPushError?: (error: unknown) => void; /** Number of operations to fetch per page. Defaults to 100. */
+  operationsPageSize?: number;
+};
+/**
+ * Result of a push operation.
+ */
+type PushResult = {
+  remoteDocument: RemoteDocumentData;
+  actionCount: number; /** The actions that were sent to the server (after signing, if applicable). */
+  operations: ReadonlyArray<Action$1>;
+};
+/**
+ * Sync status of the controller.
+ */
+type SyncStatus$1 = {
+  pendingActionCount: number;
+  connected: boolean;
+  documentId: string;
+  remoteRevision: Record<string, number>;
+};
+/**
+ * A tracked action with operation context for signing.
+ */
+type TrackedAction = {
+  action: Action$1;
+  prevOpHash: string;
+  prevOpIndex: number;
+};
+/** Information about a detected conflict. */
+type ConflictInfo = {
+  /** Remote operations added since the last pull, grouped by scope. */remoteOperations: Record<string, RemoteOperation[]>; /** Local actions pending push. */
+  localActions: TrackedAction[]; /** Remote revision at last pull. */
+  knownRevision: Record<string, number>; /** Current remote revision. */
+  currentRevision: Record<string, number>;
+};
+/** Custom merge handler receives conflict info and returns actions to push (or throws to abort). */
+type MergeHandler = (conflict: ConflictInfo) => Action$1[] | Promise<Action$1[]>;
+/** Conflict resolution strategy. */
+type ConflictStrategy = "reject" | "rebase" | MergeHandler;
+/** Event emitted when the document changes. */
+type RemoteDocumentChangeEvent = {
+  source: "action" | "pull";
+  document: PHDocument$1<PHBaseState>;
+};
+/** Listener for document change events. */
+type DocumentChangeListener = (event: RemoteDocumentChangeEvent) => void;
+/** Result of fetching operations. */
+type GetOperationsResult = {
+  operationsByScope: Record<string, RemoteOperation[]>;
+};
+/** Result of fetching a document together with its operations. */
+type GetDocumentWithOperationsResult = {
+  document: RemoteDocumentData;
+  childIds: ReadonlyArray<string>;
+  operations: GetOperationsResult;
+};
+interface IRemoteClient {
+  getDocument(identifier: string, branch?: string): Promise<GetDocumentResult | null>;
+  /** Fetch document metadata and operations in a single call. */
+  getDocumentWithOperations(identifier: string, branch?: string, sinceRevision?: Record<string, number>, scopes?: string[]): Promise<GetDocumentWithOperationsResult | null>;
+  getAllOperations(documentId: string, branch?: string, sinceRevision?: Record<string, number>, scopes?: string[]): Promise<GetOperationsResult>;
+  pushActions(documentIdentifier: string, actions: ReadonlyArray<NonNullable<unknown>>, branch?: string): Promise<RemoteDocumentData>;
+  createDocument(document: NonNullable<unknown>, parentIdentifier?: string): Promise<RemoteDocumentData>;
+  createEmptyDocument(documentType: string, parentIdentifier?: string): Promise<RemoteDocumentData>;
+  deleteDocument(identifier: string, propagate?: PropagationMode$1): Promise<boolean>;
+}
+type GetDocumentResult = {
+  document: RemoteDocumentData;
+  childIds: ReadonlyArray<string>;
+};
+interface IRemoteController<TState extends PHBaseState = PHBaseState> {
+  readonly header: PHDocumentHeader;
+  readonly state: TState;
+  readonly operations: DocumentOperations;
+  readonly document: PHDocument$1<TState>;
+  readonly status: SyncStatus$1;
+  onChange(listener: DocumentChangeListener): () => void;
+  push(): Promise<PushResult>;
+  pull(): Promise<RemoteDocumentData>;
+  delete(propagate?: PropagationMode$1): Promise<boolean>;
+}
+//#endregion
+//#region src/graphql-client/adapter.d.ts
+/** The `document` payload of a `GetDocument` query, once the null case is handled. */
+type GetDocumentQueryResult = NonNullable<GetDocumentQuery["document"]>;
+/** The `PHDocumentFields` fragment as returned by `GetDocument`. */
+type GetDocumentQueryFields = GetDocumentQueryResult["document"];
+/** The `revisionsList` selection of the `PHDocumentFields` fragment. */
+type RevisionsListSelection = GetDocumentQueryFields["revisionsList"];
+/**
+ * Converts a `GetDocument` result into a `PHDocument`.
+ *
+ * Unlike the legacy `src/graphql/adapters.ts` this preserves the per-scope
+ * revision map, which the write path needs to compute the `prevOpIndex` of a
+ * signed action. `sig` is filled with the empty shape used by
+ * `createPresignedHeader`: the creation signature is not fetchable over
+ * GraphQL and is not part of the operation signing payload.
+ *
+ * The read path never fetches operation history, so `operations` is a map of
+ * the document's known scopes to empty arrays.
+ *
+ * `branch` is the branch the document was read from. The GraphQL type does not
+ * carry it, so it has to be passed back in by the caller; it defaults to the
+ * server's own default branch.
+ */
+declare function phDocumentFromGetDocument<TDocument extends PHDocument = PHDocument>(document: GetDocumentQueryFields, branch?: string): TDocument;
+/**
+ * Converts a mutation result into a `PHDocument`, carrying the operations the
+ * mutation produced.
+ *
+ * `dispatchActions` reads per-action failures out of `operations[scope]`, so
+ * unlike the read path this one must not return empty operation lists.
+ */
+declare function phDocumentFromMutation<TDocument extends PHDocument = PHDocument>(document: GetDocumentQueryFields, operations: readonly RemoteOperation[], branch?: string): TDocument;
+/** Turns a `revisionsList` selection into the header's per-scope revision map. */
+declare function revisionMapFromRevisionsList(revisionsList: RevisionsListSelection): Record<string, number>;
+//#endregion
+//#region src/graphql-client/auth.d.ts
+/**
+ * Resolves the bearer token to send with a request.
+ *
+ * Returning `undefined` (or an empty string) means "send this request
+ * anonymously": open Switchboards must keep serving reads to logged-out users.
+ */
+type BearerTokenProvider = () => Promise<string | undefined>;
+/**
+ * The default token provider: the token of the currently logged-in Renown user.
+ *
+ * It is deliberately resolved from `window.ph` on every call rather than
+ * captured at construction time, so a client built before login starts sending
+ * the token as soon as there is one.
+ *
+ * The token is requested WITHOUT an `aud` claim - the Switchboard verifier
+ * rejects tokens that carry an audience.
+ */
+declare function ambientRenownTokenProvider(): Promise<string | undefined>;
+/**
+ * Builds the SDK middleware that authenticates every request.
+ *
+ * The token is resolved per request and never cached, so a login, a logout or
+ * an expiry between two calls is picked up by the next one. When no token is
+ * available the request goes out unauthenticated.
+ */
+declare function makeAuthMiddleware(tokenProvider: BearerTokenProvider): SdkFunctionWrapper;
+//#endregion
+//#region src/graphql-client/subgraph.d.ts
+/**
+ * The factory a GraphQL code generator produces for a schema.
+ *
+ * It is the signature of `getSdk` emitted by the `typescript-graphql-request`
+ * plugin - the generated `getSdk` in `src/graphql/gen/schema.ts` is the
+ * canonical example - so a project can hand its own generated function straight
+ * to {@link SubgraphSdkRegistry.get} and keep every operation typed.
+ */
+type SubgraphSdkFactory<TSdk> = (client: GraphQLClient, withWrapper?: SdkFunctionWrapper) => TSdk;
+/**
+ * A GraphQL document that carries its result and variable types.
+ *
+ * This is the shape a code generator gives a document (`TypedDocumentNode`),
+ * declared structurally so that reactor-browser needs no dependency on
+ * `@graphql-typed-document-node/core`. A plain `DocumentNode` satisfies it too,
+ * with the result type falling back to whatever the caller passes explicitly.
+ */
+type TypedGraphQLDocument<TResult, TVariables> = DocumentNode & {
+  __apiType?: (variables: TVariables) => TResult;
+};
+/** Extras for a one-off request. */
+type GraphQLRequestOptions = {
+  /**
+   * The operation name reported to the auth and logging middleware. Read off
+   * the document when it is not given.
+   */
+  operationName?: string;
+  /**
+   * The operation type reported to the middleware, e.g. `"mutation"`. Read off
+   * the document when it is not given.
+   */
+  operationType?: string;
+  signal?: AbortSignal;
+};
+/**
+ * Derives a subgraph's endpoint from the Switchboard's GraphQL endpoint.
+ *
+ * Subgraphs are served next to the supergraph, at `<graphql base>/<name>`, so
+ * `http://localhost:4001/graphql` plus `statements` is
+ * `http://localhost:4001/graphql/statements`.
+ */
+declare function subgraphUrlFromGraphqlUrl(url: string, name: string): string;
+/**
+ * Reads the operation name and type off a document, for the middleware.
+ *
+ * Nothing depends on getting this right - it is reported to the middleware, not
+ * sent to the server - so an unreadable document falls back to an anonymous
+ * query rather than throwing.
+ */
+declare function describeGraphQLDocument(document: string | DocumentNode): {
+  operationName: string;
+  operationType: string;
+};
+/**
+ * Binds typed subgraph SDKs to one Switchboard's transport and auth.
+ *
+ * Every capability a Switchboard exposes lives behind the same base URL, so an
+ * app should not have to build a second client - with a second copy of the auth
+ * configuration - to reach a project's own subgraph. The registry derives the
+ * endpoint, reuses one transport per subgraph and hands the code generator's
+ * `getSdk` the very middleware the reactor operations already go through.
+ *
+ * Transport and typing only: subgraph results are not cached and produce no
+ * change events.
+ */
+declare class SubgraphSdkRegistry {
+  private readonly url;
+  private readonly middleware;
+  private readonly bindings;
+  constructor(url: string, middleware?: SdkFunctionWrapper);
+  /**
+   * Returns the subgraph's SDK, building it on first use.
+   *
+   * The transport is kept per subgraph name, so repeated calls do not rebuild
+   * it. The SDK itself is only reused when the same factory is passed again -
+   * two different generated SDKs over one subgraph each get their own, rather
+   * than the second call being handed the first one's methods.
+   */
+  get<TSdk>(name: string, getSdk: SubgraphSdkFactory<TSdk>): TSdk;
+  /** Returns the subgraph's endpoint, for diagnostics and tests. */
+  urlFor(name: string): string;
+  private binding;
+}
+//#endregion
+//#region src/graphql-client/graphql-reactor-client.d.ts
+type GraphQLReactorClientOptions = {
+  /** The Switchboard GraphQL endpoint, e.g. `http://localhost:4001/graphql`. */url: string;
+  /**
+   * A pre-built SDK to use instead of the transport derived from `url`.
+   * Mainly a test seam.
+   *
+   * A client built this way carries no auth middleware: the injected SDK owns
+   * its own transport, and therefore its own headers.
+   */
+  graphqlClient?: ReactorGraphQLClient;
+  /**
+   * Resolves the bearer token sent with every request, per request.
+   *
+   * Defaults to {@link ambientRenownTokenProvider}, i.e. the token of the
+   * logged-in Renown user, or none when nobody is logged in.
+   */
+  tokenProvider?: BearerTokenProvider;
+  /**
+   * The Switchboard GraphQL subscriptions endpoint, e.g.
+   * `ws://localhost:4001/graphql/subscriptions`.
+   *
+   * Defaults to the endpoint derived from `url` by
+   * {@link subscriptionsUrlFromGraphqlUrl}.
+   */
+  subscriptionsUrl?: string;
+  /**
+   * Whether server-pushed changes are delivered to subscribers.
+   *
+   * On by default: the first `subscribe` call opens a websocket and every
+   * change the Switchboard reports is emitted to matching subscribers, so
+   * documents another user, tab or processor writes invalidate the cache.
+   *
+   * Set it to `false` where there is no websocket to talk to. The client then
+   * only emits the changes it made itself.
+   */
+  realtime?: boolean;
+};
+/**
+ * The marker {@link isGraphQLReactorClient} looks for.
+ *
+ * A page can end up with two copies of this module - an app that bundles a
+ * package carrying its own copy, or a dev server that hot-replaced it - and
+ * then `instanceof` compares an instance against the other copy's class object
+ * and answers `false`. A branded property survives both.
+ */
+declare const graphQLReactorClientBrand: "__powerhouseGraphQLReactorClient";
+/**
+ * A light implementation of {@link IReactorBrowserClient} that talks plain
+ * GraphQL to a Switchboard, with no reactor in the bundle.
+ *
+ * It fills the same `window.ph` slots the full in-browser reactor client fills,
+ * so the reactor-browser hooks cannot tell the two apart.
+ */
+declare class GraphQLReactorClient implements IReactorBrowserClient$1 {
+  /** See {@link isGraphQLReactorClient}. */
+  readonly [graphQLReactorClientBrand] = true;
+  private readonly sdk;
+  private readonly subgraphs;
+  private readonly listeners;
+  private readonly tokenProvider;
+  private readonly subscriptionsUrl;
+  private stopRealtime;
+  private realtimeStarted;
+  private realtimeGeneration;
+  private realtimeErrorLogged;
+  constructor(options: GraphQLReactorClientOptions);
+  get<TDocument extends PHDocument>(identifier: string, view?: ViewFilter, signal?: AbortSignal): Promise<TDocument>;
+  getOperations(documentIdentifier: string, view?: ViewFilter, filter?: OperationFilter, paging?: PagingOptions, signal?: AbortSignal): Promise<PagedResults<Operation>>;
+  create<TDocument extends PHDocument = PHDocument>(document: PHDocument, parentIdentifier?: string, signal?: AbortSignal): Promise<TDocument>;
+  /**
+   * Pushes actions to the Switchboard and returns the updated document.
+   *
+   * The document is fetched first: the response is the baseline for the
+   * `sinceRevision` filter that narrows the returned operations to the ones
+   * this call appended, and it carries the state hash a signed action is
+   * stamped with.
+   *
+   * The emitted `Updated` event carries the document's id, never the
+   * identifier this was called with: subscribers - including `DocumentCache` -
+   * work in id space.
+   */
+  execute<TDocument extends PHDocument>(documentIdentifier: string, branch: string, actions: Action[], signal?: AbortSignal): Promise<TDocument>;
+  /**
+   * Deletes a document and announces it as a `Deleted` event.
+   *
+   * Pass a document id. The server resolves a slug just as happily, but
+   * `deleteDocument` returns a boolean - there is no document left to read an
+   * id off - so the identifier is announced verbatim on `context.childId`. A
+   * subscriber keyed by id, `DocumentCache` included, therefore only reacts to
+   * a delete by id.
+   */
+  deleteDocument(identifier: string, propagate?: PropagationMode, signal?: AbortSignal): Promise<void>;
+  /**
+   * Registers a change subscriber and returns its unsubscribe function.
+   *
+   * Two things produce the events delivered here. Every successful `create`,
+   * `execute` and `deleteDocument` emits one, which is what makes a
+   * `DocumentCache` built on this client invalidate after a dispatch. And,
+   * unless realtime is switched off, the first call to this method opens a
+   * websocket to the Switchboard and every change it reports - from another
+   * user, another tab or a server-side processor - is emitted too. A write of
+   * this client's own is therefore announced twice, once locally and once by
+   * the server; the cache refetches twice, which is harmless.
+   *
+   * A websocket that cannot be opened or is refused is logged once and then
+   * ignored: realtime is an enhancement, never a dependency. The failed socket
+   * is closed, so the next subscriber to arrive tries again.
+   *
+   * `view` is accepted for interface compatibility and ignored: the emitted
+   * documents are whatever the write returned, so there is nothing to re-scope.
+   *
+   * Events live in id space: `search.ids` is matched against the resolved
+   * document id, never against the identifier the write was issued with. The
+   * one exception is `deleteDocument`, which has no document to resolve an id
+   * from - see its own note. A `DocumentCache` on this client must therefore
+   * be read by id: a slug-keyed entry is never invalidated.
+   */
+  subscribe(search: SearchFilter, callback: (event: DocumentChangeEvent) => void, view?: ViewFilter): () => void;
+  /**
+   * Closes the realtime socket, if one was opened.
+   *
+   * Registered subscribers are left in place: they still receive the events
+   * this client produces itself.
+   *
+   * Disposing is NOT final - a later `subscribe` opens a new socket. React
+   * remounts a tree by running an effect's cleanup and then the effect again,
+   * on the same client, and `StrictMode` does exactly that on every mount; a
+   * terminal flag here would leave those pages without realtime for good, with
+   * nothing logged.
+   */
+  dispose(): void;
+  /**
+   * Binds a project's generated SDK to this client's transport and auth.
+   *
+   * Subgraphs are served next to the reactor's own supergraph, so the endpoint
+   * is derived from the client's `url` by appending the name, and the SDK is
+   * handed the same auth middleware every reactor call goes through. An app
+   * therefore configures one URL and one token provider, and reaches every
+   * capability of its Switchboard through this one client.
+   *
+   * `getSdk` is the function a GraphQL code generator emits for the subgraph's
+   * schema - see the README in this folder for the codegen recipe.
+   *
+   * Transport and typing only. Subgraph results are not cached, produce no
+   * change events and never reach `useDocument`.
+   */
+  subgraph<TSdk>(name: string, getSdk: SubgraphSdkFactory<TSdk>): TSdk;
+  /**
+   * Runs a one-off GraphQL document against the Switchboard's own endpoint,
+   * through the same transport and auth as everything else.
+   *
+   * The escape hatch for an operation not worth generating an SDK for. Pass a
+   * document a code generator typed and the result type follows; pass a plain
+   * `gql` document or a string and name the result type at the call site.
+   */
+  request<TResult = unknown, TVariables extends Variables = Variables>(document: TypedGraphQLDocument<TResult, TVariables> | string, variables?: TVariables, options?: GraphQLRequestOptions): Promise<TResult>;
+  /**
+   * Opens the realtime socket on the first subscriber.
+   *
+   * The subscription is a firehose - no `search` argument - and this client
+   * applies each subscriber's own filter on the way out, exactly as it does for
+   * its own emissions.
+   */
+  private startRealtime;
+  /**
+   * Gives up on a failed socket so that a later subscriber can try again.
+   *
+   * `graphql-ws` retries on its own and only reports here once it has given up,
+   * or once the server refused the subscription outright - which is what an
+   * auth-enabled Switchboard does to an anonymous subscriber. Keeping the dead
+   * stop function would make every later `subscribe` a no-op, so realtime would
+   * stay off for the life of the page even after the user signs in.
+   *
+   * The generation stamp discards a report from a socket that has already been
+   * replaced or disposed.
+   */
+  private handleRealtimeFailure;
+  /** Closes the socket and lets a later subscriber open a new one. */
+  private teardownRealtime;
+  /** Maps a server event onto the client-side event and emits it. */
+  private emitServerEvent;
+  /**
+   * Reports a broken realtime socket once per client, however many sockets it
+   * goes through.
+   *
+   * `graphql-ws` retries on its own, and a Switchboard without a websocket
+   * endpoint would otherwise fill the console for as long as the page is open.
+   */
+  private logRealtimeError;
+  /**
+   * Delivers an event to every matching subscriber.
+   *
+   * A subscriber that throws is logged and skipped so one bad listener cannot
+   * stop the others from being notified.
+   */
+  private emitChange;
+}
+/**
+ * Whether a value is a {@link GraphQLReactorClient}, including one built by
+ * another copy of this module.
+ *
+ * Use this rather than `instanceof`: the brand it tests for is shared by every
+ * copy of the class, so a client built by a hot-replaced module or by a package
+ * that bundled its own copy is still recognised.
+ */
+declare function isGraphQLReactorClient(client: unknown): client is GraphQLReactorClient;
+/**
+ * Maps a reactor `ViewFilter` onto the GraphQL `ViewFilterInput`.
+ *
+ * Point-in-time reads are rejected: the Switchboard read API has no revision
+ * argument, so silently returning the head state would be wrong.
+ */
+declare function viewFilterInputFromViewFilter(view?: ViewFilter): ViewFilterInput | undefined;
+//#endregion
+//#region src/graphql-client/graphql-reactor-provider.d.ts
+declare global {
+  interface Window {
+    /** Set by {@link ensurePHEventHandlers}; see its doc comment. */
+    __phEventHandlersRegistered?: boolean;
+  }
+}
+/**
+ * Registers the `window.ph` event handlers once per page.
+ *
+ * The `set*` helpers only dispatch CustomEvents - nothing writes `window.ph`
+ * until `addPHEventHandlers` has registered the listeners that do. Registration
+ * is guarded by a marker on `window` rather than a module-level flag so that a
+ * hot module replacement, or two copies of this module, still register once.
+ */
+declare function ensurePHEventHandlers(): void;
+type GraphQLReactorProviderProps = {
+  /** The Switchboard GraphQL endpoint, e.g. `http://localhost:4001/graphql`. */url: string;
+  /**
+   * Resolves the bearer token sent with every request, per request. Defaults to
+   * the token of the logged-in Renown user, or none when nobody is logged in.
+   */
+  tokenProvider?: GraphQLReactorClientOptions["tokenProvider"];
+  /**
+   * The Switchboard GraphQL subscriptions endpoint, e.g.
+   * `ws://localhost:4001/graphql/subscriptions`. Defaults to the endpoint
+   * derived from `url`.
+   */
+  subscriptionsUrl?: GraphQLReactorClientOptions["subscriptionsUrl"];
+  /**
+   * Whether server-pushed changes are delivered. On by default; set it to
+   * `false` where there is no websocket to talk to.
+   */
+  realtime?: GraphQLReactorClientOptions["realtime"];
+  /**
+   * The attachment service the editors below this provider read attachments
+   * through, published into the same `window.ph` slot Connect publishes it in.
+   *
+   * The app constructs it: attachments are a separate package, and which
+   * storage an app talks to is the app's business. Leave it out and the slot
+   * stays empty, exactly as it is without this provider.
+   */
+  attachmentService?: PHGlobal$1["attachmentService"];
+  /**
+   * The packages the app works with, as real `DocumentModelLib`s built from
+   * each package's SUBPATH exports:
+   *
+   * ```tsx
+   * import { TodoV2 } from "my-models/document-models";
+   * import { TodoEditor } from "my-models/editors";
+   * import manifest from "my-models/manifest";
+   * <GraphQLReactorProvider url={url} packages={[{ manifest, documentModels: [TodoV2], editors: [TodoEditor] }]}>
+   * ```
+   *
+   * Published through a {@link StaticPackageManager} into the same
+   * `window.ph.vetraPackageManager` slot Connect fills, so the document-model
+   * hooks AND the editor hooks (`useEditorModules` and friends) work below
+   * this provider. Array order is precedence: hooks merge packages in order,
+   * and same-type collisions resolve to the earlier package.
+   *
+   * Import from the subpaths, never from the package ROOT: the root entry also
+   * exports the package's `processorFactory`, and module resolution happens
+   * before tree-shaking, so a root import drags processor (server-side) code
+   * into the browser bundle and can break the build outright.
+   *
+   * Optional on purpose: a light app may equally ship NO packages and let the
+   * Switchboard own the model entirely - both modes are supported.
+   */
+  packages?: readonly DocumentModelLib<any>[];
+  /**
+   * Sugar for hand-picked modules without package artifacts, wrapped via
+   * {@link packageFromDocumentModels} into one synthetic package (appended
+   * AFTER `packages` in precedence). Prefer `packages` when you have the real
+   * package - it also carries the editors.
+   */
+  documentModels?: readonly DocumentModelModule<any>[];
+  children: ReactNode;
+};
+/**
+ * Mounts a {@link GraphQLReactorClient} into the `window.ph` slots the
+ * reactor-browser hooks read, so `useDocument`, `useDispatch` and
+ * `useReactorClient` work below it against a Switchboard, with no reactor in
+ * the bundle.
+ *
+ * It fills the document slots, plus `window.ph.vetraPackageManager` when
+ * `documentModels` is given (a fixed {@link StaticPackageManager}, which makes
+ * the document-model hooks work). `window.ph.reactorClientModule` always stays
+ * empty, so full-reactor surfaces (drives, jobs, editor auto-discovery) find
+ * nothing - an app below this provider renders components it imports itself.
+ *
+ * The client is built on the client only: on the server the slots stay empty
+ * and the hooks report their normal loading states. The props are read once,
+ * when the client is built - changing `url` afterwards does not rebuild it.
+ *
+ * The effect's cleanup disposes the cache and the client's socket, and the
+ * effect rebuilds both if it runs again on the same client - which is what a
+ * `StrictMode` mount does.
+ */
+declare function GraphQLReactorProvider({
+  url,
+  tokenProvider,
+  subscriptionsUrl,
+  realtime,
+  attachmentService,
+  packages,
+  documentModels,
+  children
+}: GraphQLReactorProviderProps): react_jsx_runtime0.JSX.Element;
+/**
+ * Returns the {@link GraphQLReactorClient} mounted by
+ * {@link GraphQLReactorProvider}, or `undefined` when the slot holds something
+ * else - the full in-browser reactor client, or nothing yet.
+ *
+ * `useReactorClient` is typed as the narrow `IReactorBrowserClient` subset both
+ * implementations share. This is how a component reaches the light client's own
+ * surface, i.e. `subgraph` and `request`.
+ *
+ * The narrowing is by brand, not by `instanceof`: a page can carry two copies
+ * of this module - a bundled package with its own copy, or a hot-replaced one -
+ * and `instanceof` would then answer `false` for a perfectly good client and
+ * leave the component silently without one.
+ */
+declare function useSwitchboardClient(): GraphQLReactorClient | undefined;
+//#endregion
+//#region src/graphql-client/operations.d.ts
+/**
+ * The operation selection of `GetDocumentOperations`, lifted into a fragment so
+ * the write path can reuse `remoteOperationToLocal` on the items it selects.
+ */
+declare const ReactorOperationFieldsFragmentDoc: graphql.DocumentNode;
+/**
+ * `mutateDocument` plus the operations the mutation produced.
+ *
+ * The generated `MutateDocument` only selects the document fields, but
+ * `dispatchActions` reads per-action failures out of `result.operations[scope]`
+ * (`src/actions/dispatch.ts`), so the reducer-level errors would be lost.
+ *
+ * The operations filter keeps the extra selection to the operations this call
+ * could have appended rather than the whole history. All three of its fields
+ * matter:
+ * - `sinceRevision` is the lowest head revision across the targeted scopes, so
+ *   it is only a safe window when the selection is scope-limited as well;
+ * - `scopes` limits the response to the scopes the pushed actions target,
+ *   without it the server walks every scope of the document
+ *   (`packages/reactor/src/core/reactor.ts` `getOperations`);
+ * - `branch` must match the branch the mutation writes to, otherwise the
+ *   operations come from `main` (the server's default) while the actions were
+ *   applied elsewhere.
+ */
+declare const MutateDocumentWithOperationsDocument: graphql.DocumentNode;
+type MutateDocumentWithOperationsVariables = {
+  documentIdentifier: Scalars["String"]["input"];
+  actions: ReadonlyArray<Scalars["JSONObject"]["input"]>;
+  view?: ViewFilterInput;
+  sinceRevision?: Scalars["Int"]["input"];
+  scopes?: ReadonlyArray<Scalars["String"]["input"]>;
+  branch?: Scalars["String"]["input"];
+};
+type MutateDocumentWithOperationsResult = {
+  readonly mutateDocument: PhDocumentFieldsFragment & {
+    readonly operations?: {
+      readonly items: ReadonlyArray<RemoteOperation>;
+    } | null;
+  };
+};
+//#endregion
+//#region src/graphql-client/signing.d.ts
+/**
+ * Stamps an action with the head of the scope it targets.
+ *
+ * `prevOpHash` is the hash of the scope state the action is meant to apply to;
+ * for a document at head that is the hash of the last operation in the scope,
+ * which the read path cannot fetch, so it is recomputed from the state.
+ * `prevOpIndex` is the index of that last operation: revisions count
+ * operations and indices are zero based, so an empty scope stamps `-1`, which
+ * matches what the remote controller records.
+ */
+declare function stampAction(action: Action$1, document: PHDocument$1): Action$1;
+/**
+ * Signs a stamped action, preserving any signatures it already carries.
+ *
+ * The signer reads `context.prevOpHash` off the action, so this must run after
+ * {@link stampAction}.
+ */
+declare function signStampedAction(action: Action$1, signer: ISigner): Promise<Action$1>;
+//#endregion
+//#region src/graphql-client/static-package-manager.d.ts
+/**
+ * A fixed set of packages presented through the `IPackageManager` interface,
+ * so the package-derived hooks - `useDocumentModelModules`,
+ * `useDocumentModelModuleById`, `useEditorModules`, `useVetraPackages` - work
+ * below `GraphQLReactorProvider` exactly as they do below Connect.
+ *
+ * Connect's package manager installs, updates and removes packages at runtime.
+ * A light app instead declares its packages once, as code it imports itself
+ * (every generated package root exports `manifest`, `documentModels`, `editors`
+ * and `upgradeManifests` by name), so every mutating member throws and
+ * `subscribe` never emits. For hand-picked modules without package artifacts,
+ * {@link packageFromDocumentModels} wraps them in one synthetic package.
+ */
+declare class StaticPackageManager implements IPackageManager {
+  readonly registryUrl: null;
+  readonly packages: DocumentModelLib[];
+  constructor(packages: readonly DocumentModelLib<any>[]);
+  /**
+   * Resolves a module by document type across all packages. Mirrors the
+   * registry's semantics (`IDocumentModelRegistry.getModule`): the LATEST
+   * version wins, with `version ?? 1` as each module's default.
+   */
+  load(documentType: string): Promise<DocumentModelSource>;
+  subscribe(_handler: IPackagesListener): IPackageListerUnsubscribe;
+  getPackageSource(_packageName: string): RegistryPackageSource | null;
+  getPackageVersion(_packageName: string): string | undefined;
+  getRegistryPackages(): {
+    name: string;
+    version: string | undefined;
+  }[];
+  addPackage(_packageName: string): PackageManagerInstallResult;
+  addPackages(_packageNames: string[]): PackageManagerInstallResult[];
+  removePackage(_name: string): void;
+  updateLocalPackage(_pkg: DocumentModelLib, _version?: string): void;
+  addLocalPackage(_name: string, _loadedPackage: DocumentModelLib, _version?: string): void;
+}
+/**
+ * Wraps hand-picked modules in one synthetic `DocumentModelLib`, for apps that
+ * assemble their model list from mixed sources instead of passing whole
+ * packages. The manifest is fabricated - loose modules carry none - so prefer
+ * the `packages` prop with the real package exports when you have them: a real
+ * package also carries `editors`, which makes the editor hooks work.
+ */
+declare function packageFromDocumentModels(documentModels: readonly DocumentModelModule<any>[]): DocumentModelLib;
+//#endregion
+//#region src/graphql-client/subscriptions.d.ts
+/** The `documentChanges` payload, exactly as the Switchboard sends it. */
+type DocumentChangesEventPayload = DocumentChangesSubscription["documentChanges"];
+/** The connection payload sent with the `ConnectionInit` message. */
+type ConnectionParams = Record<string, string>;
+type DocumentChangesSubscriptionOptions = {
+  /** The websocket endpoint, e.g. `ws://localhost:4001/graphql/subscriptions`. */wsUrl: string;
+  /**
+   * Resolves the `ConnectionInit` payload. Called again on every reconnect, so
+   * a token that expired while the socket was down is refreshed on the way back
+   * up.
+   */
+  connectionParams?: () => Promise<ConnectionParams>; /** Called once per server event. */
+  onEvent: (event: DocumentChangesEventPayload) => void;
+  /**
+   * Called when the socket gives up: the retries built into `graphql-ws` are
+   * exhausted, or the server rejected the subscription. Realtime is an
+   * enhancement, so callers are expected to log and carry on.
+   */
+  onError: (error: unknown) => void;
+};
+/**
+ * Opens one `documentChanges` subscription and feeds every event to `onEvent`.
+ *
+ * The subscription is a firehose: no `search` argument, so the server sends
+ * every change the connection is allowed to see and the caller filters. This is
+ * the only module that knows about `graphql-ws`.
+ *
+ * Returns the stop function, which cancels the subscription and closes the
+ * socket. It is safe to call more than once.
+ */
+declare function startDocumentChangesSubscription(options: DocumentChangesSubscriptionOptions): () => void;
+/**
+ * Derives the websocket endpoint from the GraphQL http endpoint.
+ *
+ * `http://host/graphql` becomes `ws://host/graphql/subscriptions`, which is
+ * where the Switchboard mounts its websocket server (`packages/reactor-api`
+ * `startServer`). A URL that already speaks `ws`/`wss` only gets the path.
+ */
+declare function subscriptionsUrlFromGraphqlUrl(url: string): string;
+/**
+ * Turns a bearer token provider into `connectionParams`.
+ *
+ * The header key is the lowercase `authorization` the Switchboard's websocket
+ * context factory reads. Without a token the payload is empty: an open
+ * Switchboard serves anonymous subscribers.
+ */
+declare function makeAuthConnectionParams(tokenProvider: BearerTokenProvider): () => Promise<ConnectionParams>;
+//#endregion
+//#region src/hooks/document-cache.d.ts
+/** Returns all documents in the reactor. */
+declare const useDocumentCache: UsePHGlobalValue$1<IDocumentCache>;
+/** Sets all of the documents in the reactor. */
+declare const setDocumentCache: SetPHGlobalValue$1<IDocumentCache>;
+/** Adds an event handler for all of the documents in the reactor. */
+declare const addDocumentCacheEventHandler: () => void;
+/**
+ * Retrieves a document from the reactor and subscribes to changes using React Suspense.
+ * This hook will suspend rendering while the document is loading.
+ * @param id - The document ID to retrieve, or null/undefined to skip retrieval
+ * @returns The document if found, or undefined if id is null/undefined
+ */
+declare function useDocument(id: string | null | undefined): PHDocument$1 | undefined;
+/**
+ * Retrieves a document from the reactor and subscribes to changes without
+ * suspending or throwing. Use this when the ID might be stale (e.g., a
+ * previously selected node that has since been deleted) and the consumer
+ * wants to render a placeholder instead of crashing.
+ *
+ * Unlike {@link useGetDocumentAsync}, this hook subscribes to cache
+ * updates, so the returned state stays in sync with reactor changes.
+ *
+ * @param id - The document ID to retrieve, or null/undefined to skip retrieval
+ * @returns An object containing:
+ *   - status: "initial" | "pending" | "success" | "error"
+ *   - data: The document if successfully loaded
+ *   - isPending: Whether the document is currently loading
+ *   - error: Any error that occurred during loading (e.g., document not found)
+ *   - reload: Function to force a refetch, or undefined when no id is supplied
+ */
+declare function useDocumentSafe(id: string | null | undefined): {
+  readonly status: "initial";
+  readonly isPending: false;
+  readonly error: undefined;
+  readonly data: undefined;
+  readonly reload: undefined;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "pending";
+  readonly isPending: true;
+  readonly error: undefined;
+  readonly data: undefined;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "success";
+  readonly isPending: false;
+  readonly error: undefined;
+  readonly data: PHDocument$1;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "error";
+  readonly isPending: false;
+  readonly error: unknown;
+  readonly data: undefined;
+};
+/**
+ * Retrieves multiple documents from the reactor using React Suspense.
+ * This hook will suspend rendering while any of the documents are loading.
+ *
+ * Uses getBatch from the document cache which handles promise caching internally,
+ * ensuring stable references for useSyncExternalStore.
+ *
+ * @param ids - Array of document IDs to retrieve, or null/undefined to skip retrieval
+ * @returns An array of documents if found, or empty array if ids is null/undefined
+ */
+declare function useDocuments(ids: string[] | null | undefined): PHDocument$1[];
+/**
+ * Returns a function to retrieve a document from the cache.
+ * The returned function fetches and returns a document by ID.
+ * @returns A function that takes a document ID and returns a Promise of the document
+ */
+declare function useGetDocument(): (id: string) => Promise<PHDocument$1>;
+/**
+ * Returns a function to retrieve multiple documents from the cache.
+ * The returned function fetches and returns documents by their IDs.
+ * @returns A function that takes an array of document IDs and returns a Promise of the documents
+ */
+declare function useGetDocuments(): (ids: string[]) => Promise<PHDocument$1[]>;
+/**
+ * Retrieves a document from the reactor without suspending rendering.
+ * Returns the current state of the document loading operation.
+ * @param id - The document ID to retrieve, or null/undefined to skip retrieval
+ * @returns An object containing:
+ *   - status: "initial" | "pending" | "success" | "error"
+ *   - data: The document if successfully loaded
+ *   - isPending: Boolean indicating if the document is currently loading
+ *   - error: Any error that occurred during loading
+ *   - reload: Function to force reload the document from cache
+ */
+declare function useGetDocumentAsync(id: string | null | undefined): {
+  readonly status: "initial";
+  readonly data: undefined;
+  readonly isPending: false;
+  readonly error: undefined;
+  readonly reload: undefined;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "pending";
+  readonly isPending: true;
+  readonly error: undefined;
+  readonly data: undefined;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "success";
+  readonly isPending: false;
+  readonly error: undefined;
+  readonly data: PHDocument$1;
+} | {
+  readonly reload: () => Promise<PHDocument$1>;
+  readonly status: "error";
+  readonly isPending: false;
+  readonly error: unknown;
+  readonly data: undefined;
+};
+//#endregion
+//#region src/hooks/reactor.d.ts
+/** Returns the reactor client module (in-process or worker-backed) */
+declare const useReactorClientModule: UsePHGlobalValue<BrowserReactorClientModule | WorkerReactorClientModule>;
+/** Sets the reactor client module */
+declare const setReactorClientModule: SetPHGlobalValue<BrowserReactorClientModule | WorkerReactorClientModule>;
+/** Adds an event handler for the reactor client module */
+declare const addReactorClientModuleEventHandler: AddPHGlobalEventHandler;
+/** Returns the reactor client */
+declare const useReactorClient: UsePHGlobalValue<IReactorBrowserClient>;
+/** Sets the reactor client */
+declare const setReactorClient: SetPHGlobalValue<IReactorBrowserClient>;
+/** Adds an event handler for the reactor client */
+declare const addReactorClientEventHandler: AddPHGlobalEventHandler;
+declare const useSync: () => ISyncManager | undefined;
+declare const useSyncList: () => _powerhousedao_reactor0.Remote[];
+declare const useModelRegistry: () => IDocumentModelRegistry | undefined;
+declare const useDatabase: () => Kysely<Database> | undefined;
+declare const usePGlite: () => PGlite | undefined;
+//#endregion
+//#region src/hooks/dispatch.d.ts
+/**
+ * Returns a dispatch function for dispatching actions to a document.
+ * Used internally by other hooks to provide action dispatching capabilities.
+ * @param document - The document to dispatch actions to.
+ * @returns A tuple containing the document and a dispatch function.
+ */
+type DispatchFn<TAction> = (actionOrActions: TAction[] | TAction | undefined, onErrors?: (errors: Error[]) => void, onSuccess?: (result: PHDocument$1) => void) => void;
+type UseDispatchResult<TDocument, TAction> = readonly [TDocument | undefined, DispatchFn<TAction>];
+declare function useDispatch<TDocument = PHDocument$1, TAction = Action$1>(document: TDocument | undefined): UseDispatchResult<TDocument, TAction>;
+//#endregion
+//#region src/hooks/document-model-modules.d.ts
+declare function useDocumentModelModules(): DocumentModelModule[] | undefined;
+/**
+ * Resolves a document model module by document type, mirroring the registry's
+ * semantics (`IDocumentModelRegistry.getModule`): with `version` omitted the
+ * LATEST version of the type wins (`version ?? 1` as each module's default),
+ * with `version` given only an exact match is returned. The reactor resolves
+ * modules the same way when a document is created, so metadata read through
+ * this hook and the version a creation actually uses cannot disagree.
+ */
+declare function useDocumentModelModuleById(id: string | null | undefined, version?: number): DocumentModelModule | undefined;
+//#endregion
+//#region src/hooks/vetra-packages.d.ts
+declare const useVetraPackageManager: () => IPackageManager | undefined;
+/** Returns all of the Vetra packages loaded by the Connect instance */
+declare const useVetraPackages: () => DocumentModelLib[];
+/** Adds the Vetra package manager event handler */
+declare const addVetraPackageManagerEventHandler: () => void;
+/** Sets the Vetra package manager and registers its packages */
+declare function setVetraPackageManager(packageManager: IPackageManager): void;
+//#endregion
+//#region src/hooks/attachment-service.d.ts
+/** Returns the attachment service from window.ph */
+declare const useAttachmentService: UsePHGlobalValue<IAttachmentService>;
+/** Sets the attachment service on window.ph */
+declare const setAttachmentService: SetPHGlobalValue<IAttachmentService>;
+/** Registers the attachmentService window event handler */
+declare const addAttachmentServiceEventHandler: AddPHGlobalEventHandler;
+//#endregion
+export { isGraphQLReactorClient as $, useGetDocument as A, RemoteOperation as At, packageFromDocumentModels as B, useSyncList as C, IRemoteController as Ct, useDocumentCache as D, RemoteControllerOptions as Dt, useDocument as E, RemoteControllerGraphQLClient as Et, DocumentChangesSubscriptionOptions as F, addPromiseState as Ft, MutateDocumentWithOperationsVariables as G, stampAction as H, makeAuthConnectionParams as I, readPromiseState as It, GraphQLReactorProviderProps as J, ReactorOperationFieldsFragmentDoc as K, startDocumentChangesSubscription as L, useGetDocuments as M, SyncStatus$1 as Mt, ConnectionParams as N, TrackedAction as Nt, useDocumentSafe as O, RemoteDocumentChangeEvent as Ot, DocumentChangesEventPayload as P, DocumentCache as Pt, GraphQLReactorClientOptions as Q, subscriptionsUrlFromGraphqlUrl as R, useSync as S, IRemoteClient as St, setDocumentCache as T, PushResult as Tt, MutateDocumentWithOperationsDocument as U, signStampedAction as V, MutateDocumentWithOperationsResult as W, useSwitchboardClient as X, ensurePHEventHandlers as Y, GraphQLReactorClient as Z, useDatabase as _, ConflictStrategy as _t, setVetraPackageManager as a, describeGraphQLDocument as at, useReactorClient as b, GetDocumentWithOperationsResult as bt, useDocumentModelModuleById as c, ambientRenownTokenProvider as ct, UseDispatchResult as d, GetDocumentQueryResult as dt, viewFilterInputFromViewFilter as et, useDispatch as f, RevisionsListSelection as ft, setReactorClientModule as g, ConflictInfo as gt, setReactorClient as h, revisionMapFromRevisionsList as ht, addVetraPackageManagerEventHandler as i, TypedGraphQLDocument as it, useGetDocumentAsync as j, RemoteOperationResultPage as jt, useDocuments as k, RemoteDocumentData as kt, useDocumentModelModules as l, makeAuthMiddleware as lt, addReactorClientModuleEventHandler as m, phDocumentFromMutation as mt, setAttachmentService as n, SubgraphSdkFactory as nt, useVetraPackageManager as o, subgraphUrlFromGraphqlUrl as ot, addReactorClientEventHandler as p, phDocumentFromGetDocument as pt, GraphQLReactorProvider as q, useAttachmentService as r, SubgraphSdkRegistry as rt, useVetraPackages as s, BearerTokenProvider as st, addAttachmentServiceEventHandler as t, GraphQLRequestOptions as tt, DispatchFn as u, GetDocumentQueryFields as ut, useModelRegistry as v, DocumentChangeListener as vt, addDocumentCacheEventHandler as w, MergeHandler as wt, useReactorClientModule as x, GetOperationsResult as xt, usePGlite as y, GetDocumentResult as yt, StaticPackageManager as z };
+//# sourceMappingURL=attachment-service-BbtWv6CL.d.ts.map