@brass-build/client 0.4.0 → 0.5.0

package/src/errors.ts

@@ -1,8 +1,10 @@
 // The single error type every `@brass-build/client` call rejects with.
 //
-// One catch type, two mutually-exclusive discriminators: branch on
-// `.status` for the HTTP surface, `.code` for the hosted-UI launchers (an
-// HTTP rejection has no `code`, a launcher rejection no `status`).
+// One catch type: `.status` carries an HTTP rejection's status, and `.code`
+// names a hosted-UI launcher's failure or the code an HTTP refusal carried.
+// An HTTP refusal carries the platform's code whatever it is, so a code the
+// platform adds after this SDK was built still reaches the app. The codes
+// below are the ones an app is expected to act on.
 //   - `iframe_unavailable`: this browser / app context can't host the
 //     iframe (an app surfaces this as "open in a new tab").
 //   - `embed_error`: the embed page cannot proceed (e.g. not signed in).
@@ -10,17 +12,26 @@
 //   - `app_not_installed`: the server rejected the app's action because
 //     the target organization has no install of it; `organizationId`
 //     names the org so the install-consent flow can be offered.
+//   - `app_not_granted`: the reader can open the document, but nobody has
+//     handed it to this app. Opening it through `session.open()` does.
+//   - `not_imported`: the document's file has not been imported: another
+//     app imports it, or this app had not called `registerImporter` when
+//     the open stopped waiting for it. Show that the file has not been
+//     imported yet; a document that has it as an input lists it as changed
+//     once it has.
 export type BrassErrorCode =
   | 'not_in_browser'
   | 'iframe_unavailable'
   | 'embed_error'
   | 'app_not_installed'
-  | 'schema_conflict';
+  | 'schema_conflict'
+  | 'app_not_granted'
+  | 'not_imported';
 
 export class BrassError extends Error {
   override name = 'BrassError';
   readonly status?: number;
-  readonly code?: BrassErrorCode;
+  readonly code?: BrassErrorCode | (string & {});
   readonly organizationId?: string;
   /** Server-authored heading for a prompt this error drives, when the
    *  platform sends one. A client freezes into an app's bundle, so a string
@@ -31,7 +42,7 @@ export class BrassError extends Error {
     message: string,
     init?: {
       status?: number;
-      code?: BrassErrorCode;
+      code?: BrassErrorCode | (string & {});
       organizationId?: string;
       title?: string;
     },

package/src/fetch-retry.ts

@@ -72,6 +72,10 @@ export interface RetryOptions {
   // Invoked before each replay with the 1-based attempt that just failed and
   // the response (absent on a network throw). For diagnostics only.
   onRetry?: (attempt: number, response: Response | undefined) => void;
+  // A response in the replay set that this answers true for is returned
+  // rather than replayed: a refusal that names its own wait, which the caller
+  // paces instead of this backoff.
+  isFinal?: (response: Response) => Promise<boolean>;
   // Injected for tests; defaults to the real timer.
   sleep?: (ms: number) => Promise<void>;
 }
@@ -112,6 +116,7 @@ export async function fetchWithRetry(
     if (response && !policy.replayStatuses.has(response.status)) {
       return response;
     }
+    if (response && options.isFinal && (await options.isFinal(response))) return response;
     if (attempt === maxAttempts) {
       if (response) return response;
       throw lastError;

package/src/file-choice.ts

@@ -0,0 +1,26 @@
+// The browser's own file dialog, for a visitor with no account: there is
+// nothing of theirs to browse, so which file is the whole question.
+//
+// `input.click()` needs the user activation of the press that called it,
+// which lasts seconds rather than a task, so a short read may come first.
+// Resolves null when the dialog is dismissed (`cancel`, which every current
+// engine fires on an `<input type=file>`).
+
+export function chooseFile(accept: string): Promise<File | null> {
+  return new Promise((resolve) => {
+    const input = document.createElement('input');
+    input.type = 'file';
+    if (accept !== '') input.accept = accept;
+    input.style.display = 'none';
+    const finish = (file: File | null): void => {
+      input.remove();
+      resolve(file);
+    };
+    input.addEventListener('change', () => finish(input.files?.[0] ?? null), { once: true });
+    input.addEventListener('cancel', () => finish(null), { once: true });
+    // Attached, because a detached input does not open its dialog in every
+    // engine.
+    document.body.append(input);
+    input.click();
+  });
+}

package/src/guest-link.ts

@@ -6,9 +6,370 @@
 // Pure + search-string-in so it stays testable, mirroring
 // `isExportMode(search)`.
 
-export const GUEST_LINK_PARAM = 'brass_link';
+const GUEST_LINK_PARAM = 'brass_link';
 
 export function readGuestLinkToken(search: string): string | null {
   const value = new URLSearchParams(search).get(GUEST_LINK_PARAM);
   return value && value.trim() !== '' ? value : null;
 }
+
+// Pin the token into the page URL (`replaceState`, never a history entry):
+// a document created while signed out is reached again only through its
+// token, so a reload restores it from here, and `signIn()` carries this URL
+// as its return address.
+export function writeGuestLinkToken(token: string): void {
+  if (typeof window === 'undefined') return;
+  try {
+    const url = new URL(window.location.href);
+    url.searchParams.set(GUEST_LINK_PARAM, token);
+    const next = url.toString();
+    if (next === window.location.href) return;
+    window.history.replaceState(window.history.state, '', next);
+  } catch {
+    // History API unavailable or URL exotic: leave the URL alone.
+  }
+}
+
+export function clearGuestLinkToken(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    const url = new URL(window.location.href);
+    if (!url.searchParams.has(GUEST_LINK_PARAM)) return;
+    url.searchParams.delete(GUEST_LINK_PARAM);
+    window.history.replaceState(window.history.state, '', url.toString());
+  } catch {
+    // See `writeGuestLinkToken`.
+  }
+}
+
+// The last document a visitor created without an account, per app. The URL
+// is that document's only handle, so a visitor who closes the tab and comes
+// back to the app's root would have no way back to it; the app's signed-out
+// gate offers it from here. localStorage, since the return is in a new tab.
+// The expiry is stored beside the token so the gate can say when the work
+// is lost without a request, and an entry past it reads as absent.
+//
+// The token is a credential to an editable document, which is why the
+// session hands an app the expiry alone and opens the document itself.
+const UNSAVED_KEY_PREFIX = 'brass:unsaved:';
+
+export interface UnsavedWorkEntry {
+  token: string;
+  expiresAt: Date;
+}
+
+function unsavedStorage(): Storage | null {
+  if (typeof localStorage === 'undefined') return null;
+  try {
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function unsavedKey(appId: string): string {
+  return `${UNSAVED_KEY_PREFIX}${appId}`;
+}
+
+export function storeUnsavedWork(
+  appId: string,
+  token: string,
+  expiresAt: Date,
+): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(
+      unsavedKey(appId),
+      JSON.stringify({ token, expires_at: expiresAt.toISOString() }),
+    );
+  } catch {
+    // Quota / disabled storage. The way back is a niceness; the open that
+    // just succeeded must not fail on it.
+  }
+}
+
+export function readUnsavedWork(
+  appId: string,
+  now: number = Date.now(),
+): UnsavedWorkEntry | null {
+  const storage = unsavedStorage();
+  if (!storage) return null;
+  let raw: string | null;
+  try {
+    raw = storage.getItem(unsavedKey(appId));
+  } catch {
+    return null;
+  }
+  if (raw === null) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const entry = parsed as { token?: unknown; expires_at?: unknown } | null;
+  const expiresAt =
+    typeof entry?.expires_at === 'string' ? new Date(entry.expires_at) : null;
+  if (
+    typeof entry?.token !== 'string' ||
+    entry.token === '' ||
+    expiresAt === null ||
+    Number.isNaN(expiresAt.getTime())
+  ) {
+    return null;
+  }
+  // The platform removes the document at the expiry, so an entry past it
+  // names nothing and is dropped here rather than offered.
+  if (expiresAt.getTime() <= now) {
+    clearUnsavedWork(appId);
+    return null;
+  }
+  return { token: entry.token, expiresAt };
+}
+
+export function clearUnsavedWork(appId: string): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(unsavedKey(appId));
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+}
+
+// Whether this browser has edited a document it made without an account. New
+// and Upload ask before replacing one, so the marker outlives a reload; it
+// carries the document's expiry so an entry past it is dropped on read.
+const EDITED_KEY_PREFIX = 'brass:trial-edited:';
+
+export function markTrialEdited(token: string, expiresAt: Date): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(`${EDITED_KEY_PREFIX}${token}`, expiresAt.toISOString());
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+}
+
+export function trialWasEdited(token: string, now: number = Date.now()): boolean {
+  const storage = unsavedStorage();
+  if (!storage) return false;
+  let raw: string | null;
+  try {
+    raw = storage.getItem(`${EDITED_KEY_PREFIX}${token}`);
+  } catch {
+    return false;
+  }
+  if (raw === null) return false;
+  const expiresAt = Date.parse(raw);
+  if (Number.isNaN(expiresAt) || expiresAt <= now) {
+    try {
+      storage.removeItem(`${EDITED_KEY_PREFIX}${token}`);
+    } catch {
+      // See `storeUnsavedWork`.
+    }
+    return false;
+  }
+  return true;
+}
+
+// The claim secret the mint handed this browser, one per document, keyed by
+// the app and the document's link token. Only the browser that made the
+// document has one, so a sign-in here keeps the document and a sign-in
+// wherever its link was shared does not. Written at the mint alone, so opening
+// a shared link leaves it alone. Every mint prunes the secrets whose document
+// has expired, since nothing else removes the secret of a document nobody
+// came back to.
+const CLAIM_KEY_PREFIX = 'brass:claim:';
+
+function claimKey(appId: string, token: string): string {
+  return `${CLAIM_KEY_PREFIX}${appId}:${token}`;
+}
+
+// Collected before any removal, since removing a key renumbers the rest.
+function claimKeys(storage: Storage, prefix: string): string[] {
+  const keys: string[] = [];
+  try {
+    for (let i = 0; i < storage.length; i++) {
+      const key = storage.key(i);
+      if (key !== null && key.startsWith(prefix)) keys.push(key);
+    }
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+  return keys;
+}
+
+function readClaimEntry(
+  storage: Storage,
+  key: string,
+  now: number,
+): string | null {
+  let entry: { secret?: unknown; expires_at?: unknown } | null;
+  try {
+    entry = JSON.parse(storage.getItem(key) ?? 'null') as typeof entry;
+  } catch {
+    entry = null;
+  }
+  const expiresAt =
+    typeof entry?.expires_at === 'string' ? Date.parse(entry.expires_at) : NaN;
+  if (typeof entry?.secret !== 'string' || Number.isNaN(expiresAt) || expiresAt <= now) {
+    try {
+      storage.removeItem(key);
+    } catch {
+      // See `storeUnsavedWork`.
+    }
+    return null;
+  }
+  return entry.secret;
+}
+
+function pruneClaimSecrets(storage: Storage, now: number): void {
+  for (const key of claimKeys(storage, CLAIM_KEY_PREFIX)) readClaimEntry(storage, key, now);
+}
+
+export function storeClaimSecret(
+  appId: string,
+  token: string,
+  secret: string,
+  expiresAt: Date,
+  now: number = Date.now(),
+): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  pruneClaimSecrets(storage, now);
+  try {
+    storage.setItem(
+      claimKey(appId, token),
+      JSON.stringify({ secret, expires_at: expiresAt.toISOString() }),
+    );
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+}
+
+export function readClaimSecret(
+  appId: string,
+  token: string,
+  now: number = Date.now(),
+): string | null {
+  const storage = unsavedStorage();
+  if (!storage) return null;
+  return readClaimEntry(storage, claimKey(appId, token), now);
+}
+
+// One document's secret, or with no token every secret this browser holds
+// for the app.
+export function clearClaimSecret(appId: string, token?: string): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  const keys =
+    token === undefined
+      ? claimKeys(storage, `${CLAIM_KEY_PREFIX}${appId}:`)
+      : [claimKey(appId, token)];
+  for (const key of keys) {
+    try {
+      storage.removeItem(key);
+    } catch {
+      // See `storeUnsavedWork`.
+    }
+  }
+}
+
+// That this tab started a sign-in from a guest page, and on which token. Per
+// tab (sessionStorage), written by `signIn()` and taken once on the return,
+// so a URL carrying `brass_code` that this tab did not ask for claims nothing.
+const SIGN_IN_INTENT_PREFIX = 'brass:claim-intent:';
+
+function tabStorage(): Storage | null {
+  if (typeof sessionStorage === 'undefined') return null;
+  try {
+    return sessionStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function markClaimIntent(appId: string, token: string): void {
+  try {
+    tabStorage()?.setItem(`${SIGN_IN_INTENT_PREFIX}${appId}`, token);
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+}
+
+export function takeClaimIntent(appId: string): string | null {
+  const storage = tabStorage();
+  if (!storage) return null;
+  try {
+    const token = storage.getItem(`${SIGN_IN_INTENT_PREFIX}${appId}`);
+    storage.removeItem(`${SIGN_IN_INTENT_PREFIX}${appId}`);
+    return token;
+  } catch {
+    return null;
+  }
+}
+
+// The documents this browser claimed, per app, by the mint link each claim
+// revoked. Reading that link again answers 410 for everyone, and a page that
+// holds no session cannot ask the platform where it leads, so this is how a
+// signed-out page on it knows to offer sign-in to the document instead. It
+// confers no access (the open after sign-in is checked like any other), so a
+// sign-out keeps it. Entries lapse after `CLAIMED_LINK_TTL_MS`.
+const CLAIMED_KEY_PREFIX = 'brass:claimed:';
+const CLAIMED_LINK_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+function claimedKey(appId: string, token: string): string {
+  return `${CLAIMED_KEY_PREFIX}${appId}:${token}`;
+}
+
+function readClaimedEntry(storage: Storage, key: string, now: number): string | null {
+  let entry: { doc_id?: unknown; claimed_at?: unknown } | null;
+  try {
+    entry = JSON.parse(storage.getItem(key) ?? 'null') as typeof entry;
+  } catch {
+    entry = null;
+  }
+  const claimedAt = typeof entry?.claimed_at === 'number' ? entry.claimed_at : NaN;
+  if (
+    typeof entry?.doc_id !== 'string' ||
+    Number.isNaN(claimedAt) ||
+    claimedAt + CLAIMED_LINK_TTL_MS <= now
+  ) {
+    try {
+      storage.removeItem(key);
+    } catch {
+      // See `storeUnsavedWork`.
+    }
+    return null;
+  }
+  return entry.doc_id;
+}
+
+export function storeClaimedLink(
+  appId: string,
+  token: string,
+  docId: string,
+  now: number = Date.now(),
+): void {
+  const storage = unsavedStorage();
+  if (!storage) return;
+  for (const key of claimKeys(storage, CLAIMED_KEY_PREFIX)) readClaimedEntry(storage, key, now);
+  try {
+    storage.setItem(claimedKey(appId, token), JSON.stringify({ doc_id: docId, claimed_at: now }));
+  } catch {
+    // See `storeUnsavedWork`.
+  }
+}
+
+export function readClaimedLink(
+  appId: string,
+  token: string,
+  now: number = Date.now(),
+): string | null {
+  const storage = unsavedStorage();
+  if (!storage) return null;
+  return readClaimedEntry(storage, claimedKey(appId, token), now);
+}

package/src/handle-types.ts

@@ -90,8 +90,9 @@ export interface Splice<E> {
 }
 
 /**
- * What changed in a list. Fires once on registration carrying the whole list
- * as a single splice, then on every change carrying only what moved.
+ * What changed in a list. Fires once on registration carrying the whole list,
+ * then on every change carrying only what moved. No splice inserts more than
+ * 10,000 elements, so a spread apply stays inside the engine's argument limit.
  *
  * A registration fire and a resync are not special cases a subscriber has to
  * recognise: both arrive as splices that replace what it was last told, so
@@ -137,28 +138,47 @@ export interface HandleOwner {
   // Stamps the next commit with the mutate origin tag and commits, so the
   // change's `origin.source` reads `'local'`.
   commitMutate(): void;
+  // Runs a handle's `mutate` body, so every commit it takes carries the
+  // origin `options` asks for and the reference writes queued inside it
+  // commit after its last one.
+  runMutate(options: MutateOptions | undefined, fn: () => void): void;
   // Classify a Loro event by what produced it. Derived from the commit's
   // `by` + origin tag, so it survives microtask-deferred delivery.
   originOf(event: unknown): ChangeSource;
+  // Report an app subscriber that threw. The handle carries on delivering to
+  // the others; this is how the app hears that its own callback failed.
+  reportSubscriberThrow(err: unknown): void;
+}
+
+/** Options every `mutate` takes. */
+export interface MutateOptions {
+  /**
+   * `false` keeps the write off the reader's Undo stack, for a pass the app
+   * runs on its own rather than one the reader asked for. Defaults to true.
+   */
+  undoable?: boolean;
 }
 
 // Public handle interfaces. Concrete classes below.
 
 export interface MapHandle<T = unknown> {
-  // Per-entry read. Returns undefined when missing.
+  /** Per-entry read. Returns undefined when missing. */
   get(entryKey: string): T | undefined;
-  // Keys currently in the map.
+  /** Keys currently in the map. */
   keys(): string[];
-  // Whether an entry exists at `entryKey`.
+  /** Whether an entry exists at `entryKey`. */
   has(entryKey: string): boolean;
-  // Mutate through a typed JS-proxy, scoped to this container; same
-  // ergonomics as `doc.mutate(d => { d.entities[id].field = ... })`.
-  mutate(fn: (draft: Record<string, T>) => void): void;
-  // ONE channel for every change whatever produced it (local / remote / undo
-  // / redo / checkout): the projection reconciles by value. The callback gets
-  // `change` and optional `origin` a render ignores. Fires once on
-  // registration with the whole map as `change.set`, then on every change
-  // (each later fire proportional to what that change wrote).
+  /** Every `[key, value]`, as a walk. Each step hands over one entry, so a
+   *  caller that does not keep them never holds the whole map at once. */
+  entries(): IterableIterator<[string, T]>;
+  /** Mutate through a typed JS-proxy, scoped to this container; same
+   *  ergonomics as `doc.mutate(d => { d.entities[id].field = ... })`. */
+  mutate(fn: (draft: Record<string, T>) => void, options?: MutateOptions): void;
+  /** ONE channel for every change whatever produced it (local / remote / undo
+   *  / redo / checkout): the projection reconciles by value. The callback gets
+   *  `change` and optional `origin` a render ignores. Fires once on
+   *  registration with the whole map as `change.set`, then on every change
+   *  (each later fire proportional to what that change wrote). */
   subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
   /**
    * Report each time this container has been delivered whole: on
@@ -175,10 +195,10 @@ export interface MapHandle<T = unknown> {
    */
   onSettled(cb: () => void): HandleUnsubscribe;
 
-  // Child handle for `entries[entryKey]` when that entry is itself a map /
-  // list. Reads see empty until the container exists; the first mutate
-  // creates it, and a subscription taken before that delivers the container
-  // whole on whichever write creates it.
+  /** Child handle for `entries[entryKey]` when that entry is itself a map /
+   *  list. Reads see empty until the container exists; the first mutate
+   *  creates it, and a subscription taken before that delivers the container
+   *  whole on whichever write creates it. */
   map<U>(entryKey: string): MapHandle<U>;
   list<U>(entryKey: string): ListHandle<U>;
 }
@@ -202,12 +222,16 @@ export interface ListDraft<T> extends Array<T> {
 
 export interface ListHandle<T = unknown> {
   length(): number;
-  mutate(fn: (draft: ListDraft<T>) => void): void;
-  // Fires once on registration carrying the whole list as one splice, then on
-  // every change carrying only what moved, so a subscriber applies splices to
-  // what it already holds and never re-reads. A keyed collection belongs in a
-  // map (or `orderedMap`), which reconciles by key; a list is for ordering
-  // keys and small positional data.
+  /** The element at `index`, or undefined outside the list. */
+  get(index: number): T | undefined;
+  /** Every element in order, as a walk. */
+  values(): IterableIterator<T>;
+  mutate(fn: (draft: ListDraft<T>) => void, options?: MutateOptions): void;
+  /** Fires once on registration carrying the whole list, then on
+   *  every change carrying only what moved, so a subscriber applies splices to
+   *  what it already holds and never re-reads. A keyed collection belongs in a
+   *  map (or `orderedMap`), which reconciles by key; a list is for ordering
+   *  keys and small positional data. */
   subscribe(cb: ListSubscriber<T>): HandleUnsubscribe;
   /**
    * Report each time this container has been delivered whole: on
@@ -255,36 +279,38 @@ export type OrderedMapPosition =
   | { index: number };
 
 export interface OrderedMapHandle<T = unknown> {
-  // Per-entry read. Returns undefined when missing.
+  /** Per-entry read. Returns undefined when missing. */
   get(entryKey: string): T | undefined;
-  // Whether an entry exists in the map.
+  /** Whether an entry exists in the map. */
   has(entryKey: string): boolean;
-  // Keys in order-list order, filtered to keys still present in the map.
+  /** Keys in order-list order, filtered to keys still present in the map. */
   keys(): string[];
-  // `[key, value]` records walking the order list, so an app reading in
-  // source order doesn't re-walk the order list by hand.
+  /** Every `[key, value]` in order, as a walk. */
+  entries(): IterableIterator<[string, T]>;
+  /** @deprecated Use `entries()`, which walks the same records in the same
+   *  order without building the array. */
   ordered(): { key: string; value: T }[];
-  // Mutate the map; the sibling order list reconciles in the same commit
-  // (new keys appended in insertion order, deleted keys pruned). Drive it
-  // like `MapHandle.mutate`: `m[key] = record`, `delete m[key]`,
-  // `m[key].field = ...`.
-  mutate(fn: (draft: Record<string, T>) => void): void;
-  // Write `value` under `entryKey` and put that key at `at`, both in ONE
-  // commit (one undo step) like every other structural edit here. A key the
-  // map already holds is written and repositioned rather than named twice.
+  /** Mutate the map; the sibling order list reconciles in the same commit
+   *  (new keys appended in insertion order, deleted keys pruned). Drive it
+   *  like `MapHandle.mutate`: `m[key] = record`, `delete m[key]`,
+   *  `m[key].field = ...`. */
+  mutate(fn: (draft: Record<string, T>) => void, options?: MutateOptions): void;
+  /** Write `value` under `entryKey` and put that key at `at`, both in ONE
+   *  commit (one undo step) like every other structural edit here. A key the
+   *  map already holds is written and repositioned rather than named twice. */
   insert(entryKey: string, value: T, at: OrderedMapPosition): void;
-  // Reposition a key the map already holds, writing the order list alone. A
-  // key the map does not hold does nothing, so a reorder racing a peer's
-  // delete of the same key leaves the delete standing.
+  /** Reposition a key the map already holds, writing the order list alone. A
+   *  key the map does not hold does nothing, so a reorder racing a peer's
+   *  delete of the same key leaves the delete standing. */
   move(entryKey: string, to: OrderedMapPosition): void;
-  // Fires once on registration (the whole map as `change.set` in order),
-  // then on every change. A field edit carries only `set` / `deleted`; a
-  // change that moves the order also carries `change.order` (live keys in
-  // order) so the app re-sequences the views it holds. A move the map does
-  // not see (an edit of the sibling order list, a merge that resequences
-  // keys already present) arrives as an `order` of its own with an empty
-  // `set`. Content stays proportional to what the change wrote; re-sequencing
-  // happens only when the order moves, and at most once per change.
+  /** Fires once on registration (the whole map as `change.set` in order),
+   *  then on every change. A field edit carries only `set` / `deleted`; a
+   *  change that moves the order also carries `change.order` (live keys in
+   *  order) so the app re-sequences the views it holds. A move the map does
+   *  not see (an edit of the sibling order list, a merge that resequences
+   *  keys already present) arrives as an `order` of its own with an empty
+   *  `set`. Content stays proportional to what the change wrote; re-sequencing
+   *  happens only when the order moves, and at most once per change. */
   subscribe(cb: MapSubscriber<T>): HandleUnsubscribe;
   /**
    * Report each time this container has been delivered whole: on