@softr/sdk 0.0.54 → 0.0.56-alpha.0

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.54
+  library_version: 0.0.56-alpha.0
 ---
 
 **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.54
+  library_version: 0.0.56-alpha.0
 ---
 
 **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,10 +13,10 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.54
+  library_version: 0.0.56-alpha.0
 ---
 
-**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. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
+**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.
 
 # Reading records
 

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

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.54
+  library_version: 0.0.56-alpha.0
 ---
 
 **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.54
+  library_version: 0.0.56-alpha.0
 ---
 
 **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.54
+  library_version: 0.0.56-alpha.0
 ---
 
 **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,54 +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, in `<head>` in the root route's `RootDocument`.
- *
- * @example
- * function RootDocument({ children }: { children: React.ReactNode }) {
- *   return (
- *     <html lang="en">
- *       <head>
- *         <HeadContent />
- *         <SoftrPwaHead />
- *       </head>
- *       <body>
- *         {children}
- *         <Scripts />
- *       </body>
- *     </html>
- *   )
- * }
- */
-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,152 +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, in `<head>` in the root route's `RootDocument`.
-*
-* @example
-* function RootDocument({ children }: { children: React.ReactNode }) {
-*   return (
-*     <html lang="en">
-*       <head>
-*         <HeadContent />
-*         <SoftrPwaHead />
-*       </head>
-*       <body>
-*         {children}
-*         <Scripts />
-*       </body>
-*     </html>
-*   )
-* }
-*/
-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,77 +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, and how to check that the app is installable. The manifest and icon
-  are already served; never write them.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.54
----
-
-# 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?
-
-The builder switches installing on in Studio, and `usePwaInstall()` reads that switch at runtime. To check it before writing any code, ask the running app for `/_softr/pwa.json`: `200` means installable, `404` means installing is off or there is no icon yet. Do not build an install button against a `404`: installing has to be turned on first. A change in Studio can take up to two minutes to reach the app.
-
-## Core Patterns
-
-### The links: `<SoftrPwaHead />`
-
-Render it once, in `<head>` next to `<HeadContent />`, in `RootDocument` in `src/routes/__root.tsx`.
-
-```tsx
-function RootDocument({ children }: { children: React.ReactNode }) {
-  return (
-    <html lang="en">
-      <head>
-        <HeadContent />
-        <SoftrPwaHead />
-      </head>
-      <body>
-        {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 steps for `platform` instead: Share, then Add to Home Screen on iOS; the browser menu's Install app on Android and desktop. `name` and `iconUrl` tell the visitor what they are adding.
-
-## References
-
-- [SKILL.md](../SKILL.md): the entrypoints and which one each export lives on