@microsoft/rayfin-guide 1.35.0-alpha.1374 → 1.35.0-alpha.1412

package/assets/docs/app-backend/deep-linking.md

@@ -0,0 +1,188 @@
+---
+sidebar_position: 50
+---
+
+# Deep linking and shareable URLs
+
+Deep linking lets a user copy the browser URL and send someone the exact view they were looking at.
+
+A Fabric data app runs inside a cross-origin iframe and has no addressable URL of its own, so it cannot write to the address bar directly.
+The `@microsoft/rayfin-app-state-fabric` package bridges that gap: your app hands the portal a plain JSON object, and the portal encodes it into the URL it owns.
+
+## Availability
+
+Deep linking is rolling out per tenant, so it is not available everywhere yet.
+
+Always call `isSupported()` before showing a share button or any affordance that depends on the URL carrying state.
+It resolves to `undefined` when the host does not support deep linking, and your app should continue to work normally in that case.
+
+## How it works
+
+1. A user opens a link whose portal URL carries encoded state.
+2. The portal seeds that state onto your app's iframe URL before your app loads.
+3. Your app reads it synchronously on startup, so the shared view renders first and no default view flashes.
+4. As the user navigates, your app writes state back through the SDK and the portal updates its address bar.
+5. When the user presses Back or Forward, the portal notifies your app so it can restore the matching view.
+
+The portal owns encoding, versioning, size limits, and browser history.
+Your app owns the shape of the state object.
+
+## Install the package
+
+```bash
+npm install @microsoft/rayfin-app-state-fabric
+```
+
+## Create the client
+
+Create one client for the lifetime of your app and share it, rather than constructing one per component.
+
+```typescript
+import { createFabricAppStateClient } from '@microsoft/rayfin-app-state-fabric';
+
+const appState = createFabricAppStateClient({
+  targetOrigin: 'https://app.fabric.microsoft.com',
+});
+```
+
+Pass `targetOrigin` whenever you know it.
+Without it, messages are posted with `"*"` and inbound events are not origin-checked.
+
+## Read launch state before first render
+
+Read the launch state before your first render so a default view never flashes before the shared one.
+
+```typescript
+const launch = appState.getLaunchStateSync();
+renderApp(launch ?? defaultView);
+```
+
+`getLaunchStateSync()` returns the state without awaiting, which is what you want on the first render path.
+It returns `undefined` when the URL carries no state, which is the normal case for a fresh navigation.
+
+Use `await appState.getLaunchState()` when your startup code can be asynchronous.
+It resolves from the seeded URL on hosts that support it, so awaiting it does not delay first paint.
+
+Treat launch state as untrusted input.
+Anyone can edit a link before sharing it, so validate it exactly as you would a query parameter before using it to drive queries.
+
+## Write state as the user navigates
+
+Choose between the two writers by asking who caused the change.
+
+Use `setState()` when the *user* caused it, such as a click, a filter change, or opening a record.
+It creates a history entry, so Back returns the user to where they were.
+
+```typescript
+await appState.setState({ view: 'sales', region: 'AT' });
+```
+
+Use `replaceState()` when the *app* caused it, or for high-frequency updates such as a slider drag where one history entry per update would make Back unusable.
+
+```typescript
+await appState.replaceState({ view: 'sales', threshold: value });
+```
+
+The whole object is replaced on every write.
+There is no partial or namespaced update, so merge your state before writing it.
+
+## React to Back and Forward
+
+Subscribe to observe changes your app did not initiate, such as the browser Back and Forward buttons or a deep link opened in the current tab.
+
+```typescript
+const unsubscribe = appState.onStateChange((state) => {
+  restore(state ?? defaultView);
+});
+
+// On teardown
+unsubscribe();
+appState.dispose();
+```
+
+The listener receives `undefined` when navigation reaches a URL that carries no state, which means your app should restore its own defaults.
+
+## Check support before showing a share button
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  showShareButton();
+
+  // Some hosts can update the URL but cannot add history entries.
+  if (!capabilities.canPush) {
+    hideBackForwardHints();
+  }
+}
+```
+
+The host is authoritative.
+It reports its own `maxEncodedBytes`, `maxDepth`, and `canPush`, and those values are the real contract.
+
+## Running standalone
+
+Many apps ship standalone as well as embedded.
+Standalone, your app owns its own address bar and there is no host to talk to, so deep-link state is unavailable by design.
+
+The client is safe to construct either way.
+It never throws at construction and never rewrites a URL it does not own.
+
+Use the same `isSupported()` check to select your standalone path:
+
+```typescript
+const capabilities = await appState.isSupported();
+
+if (capabilities) {
+  await appState.setState({ view: 'sales', region: 'AT' });
+} else {
+  router.push({ path: '/sales', query: { region: 'AT' } });
+}
+```
+
+Standalone, reads return `undefined` and writes reject with `NO_HOST_WINDOW`.
+Reads degrade quietly so startup needs no branching, while writes fail loudly so a missing branch shows up during development.
+
+## Limits and rules
+
+- State must be a plain JSON object. `Date`, `Map`, `Set`, class instances, functions, and `undefined` are rejected rather than silently degraded.
+- State is capped at 4 KiB encoded and 20 levels deep, so shared links survive corporate proxies, mail gateways, and chat clients.
+- For anything larger, store the data yourself and put an identifier in the state.
+- The encoding is versioned but your payload is not, so a link shared before a shape change still arrives in the old shape and your app must tolerate it.
+
+## Security
+
+State travels in a URL, so treat it accordingly.
+
+**It is visible to the user.**
+It appears in the address bar, browser history, bookmarks, screenshots, copied links, and corporate proxy logs.
+Never put secrets, access tokens, or personal data in it.
+When the state is sensitive, use an opaque identifier that maps to server-side data.
+
+**It is untrusted input.**
+Validate launch state before using it, and tolerate state written by a different version of your own app.
+
+## Troubleshooting
+
+**`isSupported()` resolves to `undefined`.**
+Either the app is not embedded in the Fabric portal, or deep linking has not reached this tenant yet.
+Both are expected, and your app should fall back to its own routing.
+
+**Writes reject with `STATE_TOO_LARGE`.**
+The state exceeds the encoded budget the host reported.
+Move the bulk of the data server-side and keep an identifier in the state.
+
+**Writes reject with `INVALID_STATE`.**
+The state contains something JSON cannot round-trip, such as a `Date`, a class instance, `undefined`, or a circular reference.
+The error message names the offending path.
+
+**Writes reject with `NO_HOST_WINDOW`.**
+The app is not running embedded, so there is no portal to write to.
+
+Errors are `FabricAppStateError` values with a stable `code`.
+Branch on the code, never on the message.
+
+## Next steps
+
+- [Fabric Brokered Auth](../auth/fabric.md) — How Fabric SSO authentication works.
+- [Deploy to Microsoft Fabric](./deploy.md) — Detailed deployment commands and troubleshooting.

package/assets/docs/app-backend/deploy.md

@@ -266,7 +266,7 @@ services:
 
 ### Static deploy exceeds size limit
 
-The compressed archive must not exceed 100 MB. Optimize your build output by excluding source maps and large development assets, or move binary files to Rayfin storage.
+The compressed archive must not exceed 100 MB. Optimize your build output by excluding source maps and large development assets.
 
 ### GraphQL returns "Internal server error" after deploy
 

package/assets/docs/app-backend/index.md

@@ -67,7 +67,6 @@ The endpoint exposes paths for each service:
 | --- | --- |
 | `/api/graphql` | Data API (GraphQL) — used by `RayfinClient` for CRUD operations |
 | `/auth` | Authentication service |
-| `/storage` | File storage |
 
 Your frontend application uses this endpoint via the `VITE_RAYFIN_API_URL` environment variable, which is generated into `.env.local` from `rayfin/.env` after deployment.
 
@@ -123,4 +122,5 @@ Learn more about [Workspace roles](https://learn.microsoft.com/fabric/fundamenta
 - [Pricing and capacity usage](./pricing.md) — Understand what consumes Fabric capacity and how billing works.
 - [Create a Fabric data app](../getting-started/create-rayfin-item.md) — Step-by-step guide to creating your first item in the Fabric portal.
 - [Deploy to Microsoft Fabric](./deploy.md) — Detailed deployment commands and troubleshooting.
+- [Deep linking and shareable URLs](./deep-linking.md) — Let users share a link that reopens the exact view they were looking at.
 - [Fabric Brokered Auth](../auth/fabric.md) — How Fabric SSO authentication works.

package/assets/docs/cli/env-interpolation.md

@@ -145,10 +145,6 @@ services:
     enabled: ${AUTH_ENABLED:-false}
     issuer: ${AUTH_ISSUER}
     audience: ${AUTH_AUDIENCE:-https://api.example.com}
-
-  storage:
-    enabled: ${STORAGE_ENABLED:-true}
-    accountName: ${STORAGE_ACCOUNT:-devstoreaccount1}
 ```
 
 ```bash
@@ -159,7 +155,6 @@ DB_PORT=5432
 DB_NAME=todos_prod
 AUTH_ENABLED=true
 AUTH_ISSUER=https://auth.example.com
-STORAGE_ACCOUNT=prodstorageaccount
 ```
 
 ## Security Best Practices

package/assets/docs/cli/environment-variables.md

@@ -171,7 +171,6 @@ Read by the Rayfin WebService container via the ASP.NET Core configuration syste
 | --- | --- | --- |
 | `Auth__Enabled` | `services.auth.enabled` | `true` / `false` |
 | `Data__Enabled` | `services.data.enabled` | `true` / `false` |
-| `Storage__Enabled` | `services.storage.enabled` | `true` / `false` |
 
 The following signing-key variables are set to dev-mode defaults by `rayfin up` and are not typically edited:
 
@@ -190,7 +189,7 @@ These variables are read from the shell environment and are never written to fil
 | `RAYFIN_WORKSPACE_ID` | Fabric workspace ID for non-interactive setup. Used with `RAYFIN_TOKEN`. |
 | `RAYFIN_TENANT_ID` | Entra ID tenant used by `rayfin up` for portal URLs and the `ctid` query parameter. Equivalent to the `-t, --tenant <id>` flag (precedence: flag > env var > signed-in tenant). |
 | `RAYFIN_ENCRYPTION_FALLBACK_ENABLED` | Set to `true` to allow plaintext token cache on systems without OS credential storage. Development only. |
-| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `storage`, `functions`, and `postgresql`. |
+| `RAYFIN_FEATURE_FLAGS` | Comma-separated list of experimental feature names to enable (case-insensitive). Recognized values include `docker-local-dev`, `functions`, and `postgresql`. |
 | `RAYFIN_WEBSERVICE_IMAGE_NAME` | **Experimental.** Override the webservice container image used by `rayfin dev --provider docker` and Docker Compose. Defaults to `ghcr.io/microsoft/project-rayfin/webservice:cli-<version>`. |
 | `RAYFIN_APPINSIGHTS_CONNECTION_STRING` | Override the telemetry endpoint for the CLI and VS Code extension. |
 
@@ -199,7 +198,6 @@ These variables are read from the shell environment and are never written to fil
 | Flag | Effect |
 | --- | --- |
 | `docker-local-dev` | Allows `rayfin dev --provider docker` and the Docker maintenance commands. Bare `rayfin dev` remains available without this flag and defaults to Fabric. |
-| `storage` | Exposes storage commands (`rayfin dev storage *`) and storage prompts during `rayfin init`. |
 | `functions` | Exposes Functions service prompts during `rayfin init`. |
 | `postgresql` | Adds PostgreSQL as a selectable dialect during `rayfin init` and `rayfin init` with bundled templates. |
 

package/assets/docs/data/overview.md

@@ -53,6 +53,10 @@ If you omit it, the server generates a UUID automatically.
 - You may supply your own UUID at creation time if you prefer client-generated identifiers.
 - Composite or non-`id` primary keys are not supported.
 
+**Scope:** the rules above apply to entities you own under `rayfin/data/`.
+Connector entities under `rayfin/connectors/` model an existing, external Fabric SQL source and follow different rules — the primary key is whatever the source actually declares, of any name and any datatype, including composite keys or no key at all.
+See the connector skill's [Entity Generation Contract](pathname://../../../../tools/cli/assets/agent-files/skills/rayfin-connectors/SKILL.md#entity-generation-contract) section for the connector-path key rules.
+
 ```typescript
 @entity()
 export class Todo {

package/assets/docs/data/permissions.md

@@ -145,23 +145,6 @@ export class SecureDocument {
 }
 ```
 
-## Storage permissions
-
-The same `@role` decorator works with storage entities.
-When applied to a `@blob()` class, Rayfin generates a storage policy instead of a database policy:
-
-```typescript
-import { blob, role } from '@microsoft/rayfin-core';
-
-@blob()
-@role('authenticated', '*', {
-  policy: (claims, item) => claims.sub.eq(item.owner_id),
-})
-export class ProfileImage {
-  owner_id!: string;
-}
-```
-
 ## How it works
 
 - The `@role` decorator collects permission metadata at class definition time.

package/assets/docs/getting-started/project-structure.md

@@ -78,8 +78,6 @@ services:
   data:
     enabled: true
     dialect: mssql
-  storage:
-    enabled: false
   staticHosting:
     enabled: true
     root: .
@@ -160,12 +158,6 @@ Configure an email provider for magic links, password resets, and email verifica
 | `useStartTls` | `boolean` | `false` | Use STARTTLS for the SMTP connection. |
 | `webPort` | `number` | `1080` | MailDev web UI port (local development only). |
 
-#### `services.storage`
-
-| Field | Type | Default | Description |
-| --- | --- | --- | --- |
-| `enabled` | `boolean` | `false` | Enable the storage service. |
-
 #### `services.staticHosting`
 
 | Field | Type | Default | Description |

package/assets/docs/hosting/index.md

@@ -133,7 +133,7 @@ The deploy tool updates the configuration and pushes it to the backend during de
 
 - The compressed ZIP archive must not exceed **100 MB**.
 - The CLI uses maximum compression to minimize upload size.
-- If your build output exceeds the limit, consider excluding large assets or using the storage service for binary files.
+- If your build output exceeds the limit, consider excluding large assets from the deployed bundle.
 
 ## Complete example
 
@@ -182,7 +182,6 @@ If the ZIP exceeds 100 MB:
 
 - Review your build output for unnecessary files (source maps, unoptimized images).
 - Configure your bundler to exclude development artifacts from the production build.
-- Move large binary assets to Rayfin storage instead of bundling them as static content.
 
 ### No remote endpoint configured
 

package/assets/docs/preview/local-dev-docker.md

@@ -24,9 +24,9 @@ This command:
 - Validates that Docker and Docker Compose are available.
 - Generates `rayfin/.temp/docker-compose.yml` from your project configuration.
 - Allocates ports for each service.
-- Starts containers for enabled services (WebService, database, and optional storage).
+- Starts containers for enabled services (WebService and database).
 - Runs health checks and waits for all services to be healthy.
-- Applies the project's declared data and storage configuration to the local backend.
+- Applies the project's declared data configuration to the local backend.
 - Starts the frontend with `npm run dev:frontend` when that script exists, falling back to `npm run dev` for existing projects.
 - Resolves that script from `services.staticHosting.path` when the frontend lives in a nested package, otherwise from the project root.
 - Builds and starts the configured local Functions host when `services.functions.enabled` is `true`.
@@ -100,14 +100,6 @@ npx rayfin dev db apply --force
 Run this after making changes to entities in `rayfin/data/`.
 Use `--force` to regenerate configuration even if no changes are detected.
 
-### `rayfin dev storage apply`
-
-Generate and apply storage configuration to the local development server.
-
-```bash
-npx rayfin dev storage apply
-```
-
 ### `rayfin dev status`
 
 Display the status of the local development environment.
@@ -120,7 +112,7 @@ Shows container health, port assignments, and service readiness.
 
 ### `rayfin dev watch`
 
-Watch `./rayfin/data` or `./rayfin/storage` and auto-apply configuration changes.
+Watch `./rayfin/data` and auto-apply configuration changes.
 
 ```bash
 npx rayfin dev watch
@@ -153,11 +145,5 @@ Set the feature flag in your environment:
 export RAYFIN_FEATURE_FLAGS=docker-local-dev
 ```
 
-Or combine with other flags:
-
-```bash
-export RAYFIN_FEATURE_FLAGS=docker-local-dev,storage
-```
-
 This feature flag gates only Docker provider selection and Docker maintenance commands.
 Bare `rayfin dev` is available without preview flags and uses Fabric.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/rayfin-guide",
-  "version": "1.35.0-alpha.1374",
+  "version": "1.35.0-alpha.1412",
   "description": "Cross-cutting Builder guides for the Rayfin platform — discovered by `@microsoft/rayfin-docs` via the `rayfinDocs` package.json field convention.",
   "type": "module",
   "files": [