@brass-build/client 0.1.0 → 0.3.0

package/src/selection-persistence.ts

@@ -73,7 +73,16 @@ export function readLastDocument(
 ): SelectDocumentResult | null {
   const storage = getStorage();
   if (!storage) return null;
-  const raw = storage.getItem(docKey(appId));
+  let raw: string | null;
+  try {
+    raw = storage.getItem(docKey(appId));
+  } catch {
+    // A storage that holds a handle but refuses reads (a partitioned or
+    // locked-down context). Recalling the last document is a niceness, so it
+    // degrades to none rather than throwing out of the caller, which would
+    // replace the real reason a document could not be reopened.
+    return null;
+  }
   if (raw === null) return null;
   let parsed: unknown;
   try {

package/src/serializer.ts

@@ -1,4 +1,36 @@
 import type { Document } from './documents.js';
+import type { ListHandle, MapHandle } from './handle-types.js';
+
+/**
+ * A container read whole.
+ *
+ * The handles an app holds do not offer this: an app is handed its records
+ * through `subscribe`, so a fire costs what changed rather than what the
+ * document holds. A serializer is the other kind of caller. It runs detached,
+ * with no subscription to have been fed by, and it needs the document once, so
+ * it is handed a view that reads whole containers instead of being told to go
+ * and fetch them.
+ */
+export interface StoredMap<T = unknown> extends MapHandle<T> {
+  read(): Record<string, T>;
+}
+
+export interface StoredList<T = unknown> extends ListHandle<T> {
+  read(): T[];
+}
+
+/**
+ * The document as a serializer sees it: the same containers, readable whole.
+ *
+ * A `Document` satisfies this, which is what keeps a serializer the platform
+ * ships and one an app registers on one surface. The difference between them
+ * is where they run, not what they are allowed to reach.
+ */
+export interface StoredDocument {
+  readonly id: string | null;
+  map<T = unknown>(key: string): StoredMap<T>;
+  list<T = unknown>(key: string): StoredList<T>;
+}
 
 // A per-app serializer that turns an app-owned (blob) document's records
 // back into the source file's bytes: the inverse of the parse the app ran
@@ -11,5 +43,5 @@ import type { Document } from './documents.js';
 // whole job. An app with no registered serializer cannot export its blob
 // documents (the platform falls back to the stale-original passthrough).
 export type DocumentSerializer = (
-  doc: Document,
+  doc: StoredDocument & Document,
 ) => Uint8Array | Promise<Uint8Array>;

package/src/session-persistence.ts

@@ -1,13 +1,14 @@
 // Per-app sessionStorage layer for the incognito / third-party-cookie
-// fallback session token: the opaque `sid` from a `brass_code` exchange, so
-// a hard reload in a cookie-blocked browser (incognito, Safari ITP) keeps
-// the user signed in. In a normal browser the cross-site cookie carries the
-// session and nothing is written here.
+// fallback session token: the opaque pointer a `brass_code` exchange hands
+// back, so a hard reload in a cookie-blocked browser (incognito, Safari ITP)
+// keeps the user signed in. In a normal browser the cross-site cookie carries
+// the session and nothing is written here.
 //
-// The value is no more sensitive than the cookie it mirrors: an opaque
-// pointer, useless off an allowlisted Origin, gated by `approved_apps`
-// server-side, same 30-day TTL. `sessionStorage` (per-tab, dropped on tab
-// close) matches the cookie-channel UX. Keyed per-app id.
+// The pointer is bound server-side to the app it was minted for, so its
+// authority is this app and it dies with this app's per-app sign-out. That is
+// what makes it safe to persist at all, and why the key is per-app id.
+// `sessionStorage` (per-tab, dropped on tab close) matches the cookie-channel
+// UX.
 
 const KEY_PREFIX = '__brass_session_';