@microsoft/rayfin-app-state-fabric 1.36.0-alpha.1818 → 1.36.0-alpha.1917

package/README.md

@@ -1,6 +1,10 @@
 # @microsoft/rayfin-app-state-fabric
 
-Deep-link application state for Rayfin apps embedded in the Fabric portal.
+Deep-link application state for Rayfin apps embedded in the Microsoft Fabric portal.
+
+This package lets an embedded app read the state it was launched with and write state back to the portal URL.
+
+A Fabric App runs in a cross-origin iframe and has no addressable URL of its own, so the portal host owns encoding, versioning, size limits, and browser history while the app supplies an opaque JSON object.
 
 ## Getting started
 
@@ -10,11 +14,38 @@ npm install @microsoft/rayfin-app-state-fabric
 
 For more details, [visit our docs](https://aka.ms/rayfin/docs).
 
+## When to Use This Package
+
+Use this package when a user should be able to copy the browser URL and send someone the exact view they were looking at.
+
+The package is designed for browser applications embedded in the Fabric portal that need to:
+
+- restore a shared view before the first render, so no default state is painted first
+- write state back as the user navigates, with or without a browser history entry
+- react to the browser Back and Forward buttons
+- detect whether the host supports deep linking at all, since it rolls out per tenant
+
+## Exports
+
+The package exports the following public API:
+
+- `createFabricAppStateClient(options)`
+- `FabricAppStateClient`
+- `FabricAppStateClientOptions`
+- `FabricAppState`
+- `FabricAppStateValue`
+- `FabricAppStateCapabilities`
+- `FabricAppStateListener`
+- `FabricAppStateError`
+- `DEFAULT_MAX_ENCODED_BYTES`
+- `DEFAULT_MAX_DEPTH`
+
 ## Deep linking
 
 A Fabric App runs in an iframe and cannot touch the portal address bar directly.
 `createFabricAppStateClient()` lets your app read the state it was launched with and write state back, so a user can share a link that reopens the exact view they were looking at.
 
+Create one client for the lifetime of the app.
 Read launch state *before* your first render so default state never flashes:
 
 ```ts
@@ -28,10 +59,11 @@ renderApp(launch ?? defaultView);
 
 > **Leave `targetOrigin` unset.**
 > The embedding Fabric extension host does not share the portal origin in the address bar, and it varies per environment.
-> A wrong pin makes the browser drop every message silently. When omitted, messages are posted with `"*"` and inbound events are not origin-checked.
+> A wrong pin makes the browser drop every message silently.
+> When omitted, messages are posted with `"*"` and inbound events are not origin-checked.
 
 Write state as the user navigates.
-Use `setState` for navigation the user would expect the Back button to undo, and `replaceState` for transient changes such as dragging a slider:
+Use `setState` for navigation the user would expect the Back button to undo, and `replaceState` for app-driven or transient changes such as dragging a slider:
 
 ```ts
 await appState.setState({ view: 'sales-by-region', filter: 'AT' });
@@ -112,21 +144,20 @@ Branch on `isSupported()`, or catch `NO_HOST_WINDOW` if you would rather attempt
 
 State travels in a URL, so treat it accordingly.
 
-- **It is visible to the user.** It appears in the address bar, browser history, and bookmarks.
+- **It is visible to the user.**
+  It appears in the address bar, browser history, and bookmarks.
   Never put secrets, tokens, or personal data in it.
-- **It is untrusted input.** Anyone can edit a link before sending it, so validate launch state exactly as you would a query parameter before using it to drive queries.
+- **It is untrusted input.**
+  Anyone can edit a link before sending it, so validate launch state exactly as you would a query parameter before using it to drive queries.
   Your app should also tolerate state written by a different version of itself.
 
 ## Security
 
-Microsoft takes the security of our software products and services seriously, which
-includes all source code repositories in our GitHub organizations.
+Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations.
 
 **Please do not report security vulnerabilities through public GitHub issues.**
 
-For security reporting information, locations, contact information, and policies,
-please review the latest guidance for Microsoft repositories at
-[https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
+For security reporting information, locations, contact information, and policies, please review the latest guidance for Microsoft repositories at [https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
 
 ## Trademarks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-app-state-fabric",
-  "version": "1.36.0-alpha.1818",
+  "version": "1.36.0-alpha.1917",
   "description": "Deep-link application state for Rayfin apps embedded in the Fabric portal",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,8 +13,8 @@
   ],
   "type": "module",
   "dependencies": {
-    "@microsoft/rayfin-lib": "1.36.0-alpha.1818",
-    "@microsoft/fabric-embedded-host": "1.36.0-alpha.1818"
+    "@microsoft/fabric-embedded-host": "1.36.0-alpha.1917",
+    "@microsoft/rayfin-lib": "1.36.0-alpha.1917"
   },
   "devDependencies": {
     "typescript": "^5.8.3",