@softr/sdk 0.0.48-alpha.0 → 0.0.48

package/dist/auth/isomorphic.d.ts

@@ -17,7 +17,7 @@ import * as _tanstack_react_start0 from "@tanstack/react-start";
  *   requestMiddleware: [softrAuthMiddleware()],
  * }))
  */
-declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>, _tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
+declare function softrAuthMiddleware(): _tanstack_react_start0.RequestMiddlewareAfterServer<{}, readonly [_tanstack_react_start0.RequestMiddlewareAfterServer<{}, undefined, undefined>], {
   user: User | null;
   permissions: Permissions;
 }>;

package/dist/auth/isomorphic.js

@@ -4,7 +4,6 @@ import { sessionConfig } from "./config.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
 import { makePlatform } from "./platform.js";
 import { bootErrorMiddleware } from "../boot-error.js";
-import { pwaMiddleware } from "../pwa.js";
 import { createMiddleware, createServerFn, getGlobalStartContext } from "@tanstack/react-start";
 import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 
@@ -22,7 +21,7 @@ import { rootRouteId, useRouteContext } from "@tanstack/react-router";
 * }))
 */
 function softrAuthMiddleware() {
-	return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware(), pwaMiddleware()]).server(async ({ next }) => {
+	return createMiddleware({ type: "request" }).middleware([bootErrorMiddleware()]).server(async ({ next }) => {
 		async function getSession() {
 			const token = readSessionToken();
 			const cached = readSessionData(token);

package/dist/default-error-overlay.d.ts

@@ -1,4 +1,4 @@
-import * as react1 from "react";
+import * as react0 from "react";
 
 //#region src/default-error-overlay.d.ts
 type Props = {
@@ -8,6 +8,6 @@ type Props = {
 declare function DefaultErrorOverlay({
   error,
   reset
-}: Props): react1.JSX.Element;
+}: Props): react0.JSX.Element;
 //#endregion
 export { DefaultErrorOverlay };

package/dist/index.d.ts

@@ -8,7 +8,6 @@ import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedErr
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
-import { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
-export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type PwaInstall, type PwaPlatform, type SoftrContext, type SoftrDatasources, SoftrPwaHead, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -2,11 +2,10 @@ import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
 import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
 import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
-import { SoftrPwaHead, usePwaInstall } from "./pwa.js";
 import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { softrMcpMiddleware } from "./mcp.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
 import { Audience } from "./visibility/audience.js";
 
-export { Audience, DefaultErrorOverlay, SoftrPwaHead, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePwaInstall, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start3 from "@tanstack/react-start";
+import * as _tanstack_react_start2 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -37,6 +37,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start3.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start2.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.48-alpha.0";
+var version = "0.0.48";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.48-alpha.0",
+  "version": "0.0.48",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 # Softr SDK core
@@ -29,7 +29,7 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 
 | Import | Runs | Holds |
 | --- | --- | --- |
-| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `SoftrPwaHead`, `usePwaInstall`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
+| `@softr/sdk` | Both | `defineQuery`, `defineMutation`, `defineVisibility`, `guardRoute`, `assertRouteAccess`, `isAuthorized`, `checkAccess`, `Audience`, `useCurrentUser`, `useUserTimezone`, `getSoftrContext`, `initialSoftrContext`, `softrAuthMiddleware`, the error predicates, and every type |
 | `@softr/sdk/server` | Server only | `ds`, `auth`, `workflow`, `integration` |
 | `@softr/sdk/client` | Browser only | Nothing yet, reserved for browser-only utilities |
 | `@softr/sdk/vite` | Build | `softr()`, already in `vite.config.ts` |
@@ -48,7 +48,6 @@ Each sub-skill stands alone for its task and repeats the boundary above, so most
 | Sign a visitor in, out, or up | [auth/SKILL.md](./auth/SKILL.md) |
 | Call a connected third-party API (Slack, Stripe, Gmail, …) | [integrations/SKILL.md](./integrations/SKILL.md) |
 | Open the app to AI assistants over MCP | [mcp/SKILL.md](./mcp/SKILL.md) |
-| Let visitors install the app on their home screen | [pwa/SKILL.md](./pwa/SKILL.md) |
 
 ## Quick Decision Tree
 
@@ -83,9 +82,6 @@ Calling a connected third-party API (Slack, Stripe, Gmail, Google Calendar, …)
 Opening the app to an AI assistant over MCP?
   load softr-sdk/mcp
 
-Adding an install button, or making the app installable?
-  load softr-sdk/pwa
-
 Writing a server function, loader, or middleware in general?
   not a Softr concern. Use the TanStack Start skills.
 ```

package/skills/softr-sdk/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/integrations/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/mcp/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -183,7 +183,7 @@ A read the datasource turns down throws rather than coming back empty, and it th
 
 ## Typing
 
-Queries you write are type safe and a type error is shown when there's a mistake. For an in depth reference on what fields every datasource has check own project's `docs/datasources/` directory.
+Queries you write are type safe and a type error is shown when there's a mistake. For an in depth reference on what fields every datasource has, read `docs/datasources/README.md` first — it lists every registered datasource with a link to its file. Follow those links to get field ids, types, and constraints. Do not guess filenames from table names.
 
 ## References
 

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `defineVisibility`, the access functions and the error predicates come from `@softr/sdk` and work anywhere.

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.48-alpha.0
+  library_version: 0.0.48
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere.

package/dist/pwa.d.ts

@@ -1,49 +0,0 @@
-import * as react0 from "react";
-import "@tanstack/react-start";
-
-//#region src/pwa.d.ts
-
-/**
- * The links that make the app installable: its manifest and its home screen
- * icon. Render it once, anywhere in the root route; React moves the links into
- * `<head>`.
- *
- * @example
- * function RootComponent() {
- *   return (
- *     <>
- *       <SoftrPwaHead />
- *       <Outlet />
- *     </>
- *   )
- * }
- */
-declare function SoftrPwaHead(): react0.FunctionComponentElement<react0.FragmentProps>;
-type PwaPlatform = "ios" | "android" | "desktop";
-type PwaInstall = {
-  available: false;
-} | {
-  available: true;
-  /** Which steps install the app on this device. */
-  platform: PwaPlatform;
-  /** The name the home screen will show. */
-  name: string;
-  /** The icon the home screen will show. */
-  iconUrl: string;
-};
-/**
- * Whether to offer installing the app, and on which platform. Render an
- * install button only while this says `available`: it is unavailable while
- * loading, when the builder has not turned the PWA on, when Softr has switched
- * it off, and when the app already runs installed.
- *
- * @example
- * function InstallButton() {
- *   const install = usePwaInstall()
- *   if (!install.available) return null
- *   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
- * }
- */
-declare function usePwaInstall(): PwaInstall;
-//#endregion
-export { PwaInstall, PwaPlatform, SoftrPwaHead, usePwaInstall };

package/dist/pwa.js

@@ -1,147 +0,0 @@
-import { logger } from "./logger.js";
-import { fetch } from "./fetch.js";
-import { sessionConfig } from "./auth/config.js";
-import { platformApiUrl } from "./auth/platform.js";
-import { Fragment, createElement, useEffect, useState } from "react";
-import { createMiddleware } from "@tanstack/react-start";
-import { z } from "zod";
-
-//#region src/pwa.ts
-const MANIFEST_PATH = "/manifest.webmanifest";
-const ICON_PATH = "/apple-touch-icon.png";
-const INSTALL_PATH = "/_softr/pwa.json";
-const TTL_MS = 6e4;
-const CACHE_CONTROL = "public, max-age=60";
-const pwaSchema = z.object({
-	manifest: z.record(z.string(), z.unknown()),
-	install: z.object({
-		name: z.string(),
-		iconUrl: z.string()
-	})
-});
-let cached;
-/**
-* The app's PWA, or `null` when it is not installable right now. Never
-* rejects: a failure reads as not installable and is not remembered, so the
-* next request tries again.
-*/
-function readPwa() {
-	const now = Date.now();
-	if (cached !== void 0 && cached.expires > now) return cached.pwa;
-	const entry = {
-		expires: now + TTL_MS,
-		pwa: fetchPwa().catch((error) => {
-			logger.warn("Could not read the PWA settings:", error);
-			if (cached === entry) cached = void 0;
-			return null;
-		})
-	};
-	cached = entry;
-	return entry.pwa;
-}
-async function fetchPwa() {
-	const { applicationId } = sessionConfig();
-	const response = await fetch(`${await platformApiUrl()}/v1/vibe/applications/${applicationId}/pwa`, { headers: { accept: "application/json" } });
-	if (response.status === 404) return null;
-	if (!response.ok) throw new Error(`The platform answered ${response.status}`);
-	return pwaSchema.parse(await response.json());
-}
-/**
-* Serves the app's web app manifest, its home screen icon, and what an install
-* button needs to know, from the app's own origin. Every other request passes
-* through untouched.
-*
-* Answers 404, never an error page, when the app is not installable: a browser
-* silently drops a manifest it cannot parse, so a 500 there would be invisible.
-*/
-function pwaMiddleware() {
-	return createMiddleware({ type: "request" }).server(async ({ next, pathname }) => {
-		if (pathname !== MANIFEST_PATH && pathname !== ICON_PATH && pathname !== INSTALL_PATH) return next();
-		const pwa = await readPwa();
-		if (pwa === null) return new Response(null, { status: 404 });
-		if (pathname === MANIFEST_PATH) return new Response(JSON.stringify(pwa.manifest), { headers: {
-			"content-type": "application/manifest+json",
-			"cache-control": CACHE_CONTROL
-		} });
-		if (pathname === INSTALL_PATH) return Response.json(pwa.install, { headers: { "cache-control": CACHE_CONTROL } });
-		try {
-			const iconResponse = await fetch(pwa.install.iconUrl);
-			if (!iconResponse.ok) return new Response(null, { status: 404 });
-			return new Response(iconResponse.body, { headers: {
-				"content-type": "image/png",
-				"cache-control": CACHE_CONTROL
-			} });
-		} catch (error) {
-			logger.warn("Could not fetch the PWA icon:", error);
-			return new Response(null, { status: 404 });
-		}
-	});
-}
-/**
-* The links that make the app installable: its manifest and its home screen
-* icon. Render it once, anywhere in the root route; React moves the links into
-* `<head>`.
-*
-* @example
-* function RootComponent() {
-*   return (
-*     <>
-*       <SoftrPwaHead />
-*       <Outlet />
-*     </>
-*   )
-* }
-*/
-function SoftrPwaHead() {
-	return createElement(Fragment, null, createElement("link", {
-		rel: "manifest",
-		href: MANIFEST_PATH
-	}), createElement("link", {
-		rel: "apple-touch-icon",
-		href: ICON_PATH
-	}));
-}
-const installSchema = pwaSchema.shape.install;
-/**
-* Whether to offer installing the app, and on which platform. Render an
-* install button only while this says `available`: it is unavailable while
-* loading, when the builder has not turned the PWA on, when Softr has switched
-* it off, and when the app already runs installed.
-*
-* @example
-* function InstallButton() {
-*   const install = usePwaInstall()
-*   if (!install.available) return null
-*   return <button onClick={() => openSteps(install.platform)}>Install {install.name}</button>
-* }
-*/
-function usePwaInstall() {
-	const [install, setInstall] = useState({ available: false });
-	useEffect(() => {
-		if (window.matchMedia("(display-mode: standalone)").matches || "standalone" in navigator && navigator.standalone === true) return;
-		let cancelled = false;
-		fetch(INSTALL_PATH, { headers: { accept: "application/json" } }).then(async (response) => {
-			if (!response.ok) return;
-			const parsed = installSchema.safeParse(await response.json());
-			if (!parsed.success || cancelled) return;
-			setInstall({
-				available: true,
-				platform: detectPlatform(),
-				...parsed.data
-			});
-		}).catch(() => {});
-		return () => {
-			cancelled = true;
-		};
-	}, []);
-	return install;
-}
-function detectPlatform() {
-	const userAgent = navigator.userAgent;
-	if (/iPhone|iPad|iPod/.test(userAgent) || /Macintosh/.test(userAgent) && navigator.maxTouchPoints > 1) return "ios";
-	if (/Android/.test(userAgent)) return "android";
-	return "desktop";
-}
-
-//#endregion
-export { SoftrPwaHead, pwaMiddleware, usePwaInstall };

package/skills/softr-sdk/pwa/SKILL.md

@@ -1,163 +0,0 @@
----
-name: pwa
-description: >-
-  Let visitors install the app on their home screen: SoftrPwaHead for the
-  manifest and icon links, usePwaInstall to decide whether to show an install
-  button and which platform's steps to show, the PwaInstall and PwaPlatform
-  types, how to check that the app is installable, and the default install
-  button pattern. The manifest and icon are already served; never write them.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.48-alpha.0
----
-
-# Installing the app
-
-The builder turns installing on in Studio, under Settings → Mobile app, and sets the name, colour and icon there. The app already answers with its manifest and icon once they do. What the app adds is two things: the links that point the browser at them, and a button that tells visitors how to install.
-
-> **CRITICAL**: Never write a web app manifest, icon files, a service worker, or `manifest` / `apple-touch-icon` links of your own, in `public/` or in `head()`. The app already serves them from Studio's settings, and a file of your own shadows those settings.
-> **CRITICAL**: Render an install button only while `usePwaInstall()` returns `available: true`. Never show it unconditionally, never cache the answer, never replace the check with your own. Softr can switch installing off for an app, and this check is the only way that reaches the button.
-
-## Setup
-
-```ts
-import { SoftrPwaHead, usePwaInstall } from '@softr/sdk'
-import type { PwaInstall, PwaPlatform } from '@softr/sdk'
-```
-
-```ts
-type PwaPlatform = 'ios' | 'android' | 'desktop'
-
-type PwaInstall =
-  | { available: false }
-  | {
-      available: true
-      platform: PwaPlatform   // which steps install the app on this device
-      name: string            // what the home screen will show
-      iconUrl: string         // the icon the home screen will show
-    }
-```
-
-## Is the app installable?
-
-Ask the running app for `/_softr/pwa.json`. `200` means installable, and the body is the name and icon. `404` means the builder has not turned installing on, or has not uploaded an icon. Do not build an install button against a `404`: tell the builder what to turn on instead. A change in Studio can take a few minutes to reach the app.
-
-## Core Patterns
-
-### The links: `<SoftrPwaHead />`
-
-Render it once, in the root route's shell. React moves the links into `<head>`, so it can sit anywhere in the tree.
-
-```tsx
-function RootDocument({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head>
-        <HeadContent />
-      </head>
-      <body>
-        <SoftrPwaHead />
-        {children}
-        <Scripts />
-      </body>
-    </html>
-  )
-}
-```
-
-### Whether to show a button: `usePwaInstall()`
-
-It fetches after mount, so the first render, the server render included, always says `available: false`. It stays unavailable when the app is not installable, when the request fails, and when the app already runs installed from the home screen. Inside the Studio preview it says available, so the builder can see the button; installing itself only works on the published app.
-
-There is no `install()` to call. No browser opens its install dialog for this app on request, so the button opens instructions instead.
-
-### The default button pattern
-
-Start from this unless the builder asked for something else. A round floating button with a download icon, placed where it covers nothing else on screen, that opens a sheet with the steps for the visitor's platform.
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  const [open, setOpen] = useState(false)
-  if (!install.available) return null
-
-  return (
-    <>
-      <button
-        type="button"
-        aria-label={`Install ${install.name}`}
-        onClick={() => setOpen(true)}
-        className="fixed right-4 bottom-[calc(1rem+env(safe-area-inset-bottom))] z-40 size-12 rounded-full"
-      >
-        <DownloadIcon />
-      </button>
-      {open ? <InstallSteps install={install} onClose={() => setOpen(false)} /> : null}
-    </>
-  )
-}
-
-function InstallSteps({
-  install,
-  onClose,
-}: {
-  install: Extract<PwaInstall, { available: true }>
-  onClose: () => void
-}) {
-  return (
-    <dialog open onClose={onClose}>
-      <img src={install.iconUrl} alt="" width={64} height={64} />
-      <h2>Install {install.name}</h2>
-      {install.platform === 'ios' ? (
-        <ol>
-          <li>Tap the Share button in the browser's toolbar.</li>
-          <li>Choose Add to Home Screen.</li>
-          <li>Tap Add.</li>
-        </ol>
-      ) : (
-        <ol>
-          <li>Open the browser's menu.</li>
-          <li>Choose Install app, or Add to Home screen.</li>
-        </ol>
-      )}
-    </dialog>
-  )
-}
-```
-
-The markup is only the shape. Build it from the app's own components and design tokens so it looks like part of the app, and change its look, place or wording freely. What does not change is the `available` check that decides whether it renders at all.
-
-## Common Mistakes
-
-### Showing the button without the check
-
-Wrong:
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  return <button onClick={openSteps}>Install</button>
-}
-```
-
-Correct:
-
-```tsx
-function InstallButton() {
-  const install = usePwaInstall()
-  if (!install.available) return null
-  return <button onClick={openSteps}>Install {install.name}</button>
-}
-```
-
-A button that shows unconditionally stays up when installing is off, on a device that already has the app installed, and inside the installed app itself.
-
-### Adding a manifest file
-
-Wrong: creating `public/manifest.webmanifest`, `public/apple-touch-icon.png`, or a `head()` link to either.
-
-Correct: `<SoftrPwaHead />` once in the root. The builder changes the name and icon in Studio, and a file in the app would keep the old ones.
-
-## References
-
-- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on