feat(web-foldkit): parity harness and foundations for the Foldkit web app

.changeset/effect-sdk-foldkit.md

@@ -0,0 +1,5 @@
+---
+"@maple-dev/effect-sdk": minor
+---
+
+New `@maple-dev/effect-sdk/foldkit` entry point for Foldkit apps. `MapleFoldkit.make(config).instrument(appConfig)` wraps a `Runtime.makeApplication` config: Command spans are grouped under the page load or navigation that caused them, Commands that finished without a child span (focus, scroll, hover delays) are dropped, Command args export only ids and flags unless allowed by name, runtime crashes are reported with the recent Message tags, and slow `update`, `view` and DOM patch phases become spans.

.github/workflows/deploy-pr-preview.yml

@@ -190,6 +190,7 @@ jobs:
                   SMOKE_OUTCOME: ${{ steps.smoke.outcome }}
                   DESTROY_OUTCOME: ${{ steps.destroy.outcome }}
                   WEB_URL: ${{ steps.deploy.outputs.web_url }}
+                  WEB_FOLDKIT_URL: ${{ steps.deploy.outputs.web_foldkit_url }}
                   API_URL: ${{ steps.deploy.outputs.api_url }}
                   SYNC_URL: ${{ steps.deploy.outputs.sync_url }}
                   COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
@@ -231,6 +232,9 @@ jobs:
                       echo "| Service | Preview URL |"
                       echo "| :-- | :-- |"
                       printf '| Web | [%s](%s) |\n' "${WEB_URL#https://}" "$WEB_URL"
+                      if [ -n "$WEB_FOLDKIT_URL" ]; then
+                        printf '| Web (Foldkit) | [%s](%s) |\n' "${WEB_FOLDKIT_URL#https://}" "$WEB_FOLDKIT_URL"
+                      fi
                       printf '| API | [%s](%s) |\n' "${API_URL#https://}" "$API_URL"
                       printf '| Electric Sync | [%s](%s) |\n' "${SYNC_URL#https://}" "$SYNC_URL"
                       if [ -n "$INGEST_URL" ]; then

.oxlintrc.json

@@ -136,6 +136,7 @@
 		{
 			"files": [
 				"apps/web/**",
+				"packages/web-data/**",
 				"apps/cli/**",
 				"packages/ui/**",
 				"packages/domain/**",
@@ -170,7 +171,14 @@
 		// ~460 `try`/`catch` blocks and ~500 non-null assertions between them.
 		// Drop entries from this list as each is converted rather than widening it.
 		{
-			"files": ["apps/**", "scripts/**", "**/scripts/**", "examples/**", "alchemy.run.ts"],
+			"files": [
+				"apps/**",
+				"packages/web-data/**",
+				"scripts/**",
+				"**/scripts/**",
+				"examples/**",
+				"alchemy.run.ts"
+			],
 			"rules": {
 				"maple/no-try-catch": "off",
 				"typescript/no-non-null-assertion": "off"

alchemy.run.ts

@@ -52,6 +52,7 @@ import { createMapleIngest } from "./apps/ingest/alchemy.run.ts"
 import Landing from "./apps/landing/src/worker.ts"
 import LocalUi from "./apps/local-ui/src/worker.ts"
 import Web from "./apps/web/src/worker.ts"
+import WebFoldkit from "./apps/web-foldkit/src/worker.ts"
 
 // Infisical defines CLOUDFLARE_DEFAULT_ACCOUNT_ID; alchemy reads CLOUDFLARE_ACCOUNT_ID.
 if (!process.env.CLOUDFLARE_ACCOUNT_ID && process.env.CLOUDFLARE_DEFAULT_ACCOUNT_ID) {
@@ -340,6 +341,9 @@ export default Alchemy.Stack(
 		// A vite-source Worker: alchemy owns its build and dev server. Binds api as `API`.
 		const web = yield* Effect.provideService(Web, ApiWorker, api)
 		yield* serveWorker("web", web)
+		// The Foldkit dashboard beside it, on PR previews only (`fk-pr-<n>.maple.dev`).
+		const webFoldkit =
+			stage.kind === "pr" ? yield* Effect.provideService(WebFoldkit, ApiWorker, api) : undefined
 
 		// StaticSites run their production build even on `alchemy dev`, so dev uses
 		// `DEV_PROCESS_APPS` instead. Shared across instances: deployed by `us` alone.
@@ -371,6 +375,7 @@ export default Alchemy.Stack(
 			ingestUrl: urls.ingest,
 			electricSyncUrl: urls.electricSync,
 			webUrl: domains.web ? `https://${domains.web}` : "",
+			webFoldkitUrl: stage.kind === "pr" ? `https://fk-pr-${stage.prNumber}.maple.dev` : "",
 			landingUrl: domains.landing ? `https://${domains.landing}` : "",
 			localUiUrl: domains.local ? `https://${domains.local}` : "",
 		}
@@ -379,6 +384,7 @@ export default Alchemy.Stack(
 		yield* Effect.sync(() =>
 			appendStepOutputs([
 				`web_url=${summary.webUrl}`,
+				`web_foldkit_url=${summary.webFoldkitUrl}`,
 				`api_url=${summary.apiUrl}`,
 				`sync_url=${summary.electricSyncUrl}`,
 				`ingest_url=${ingest && domains.ingest ? `https://${domains.ingest}` : ""}`,
@@ -396,6 +402,7 @@ export default Alchemy.Stack(
 			apiWorker: api.workerName,
 			electricSyncWorker: electricSync.workerName,
 			webWorker: web?.workerName,
+			webFoldkitWorker: webFoldkit?.workerName,
 			landingWorker: landing?.workerName,
 			localUiWorker: localUi?.workerName,
 			alertingWorker: alerting.workerName,

apps/landing/project.inlang/.gitignore

@@ -14,10 +14,6 @@
 #
 # Inlang handles the gitignore itself starting with version ^2.5.
 #
-# everything is ignored except settings.json and Paraglide configuration
+# everything is ignored except settings.json
 *
-!settings.json
-!paraglide.config.js
-!paraglide.config.mjs
-!paraglide.config.ts
-!paraglide.config.cjs
+!settings.json

apps/local-ui-foldkit/index.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en" class="dark">
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<meta name="color-scheme" content="dark light" />
+		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<link rel="icon" href="/favicon.ico" />
+		<meta name="theme-color" content="#171410" />
+		<title>Maple Local</title>
+		<!-- Follow the OS theme before first paint so light-mode users don't see a dark
+		     flash. entry.ts takes over from here (same class + colorScheme). -->
+		<script>
+			;(() => {
+				try {
+					const theme = window.matchMedia("(prefers-color-scheme: light)").matches
+						? "light"
+						: "dark"
+					const root = document.documentElement
+					root.classList.remove("light", "dark")
+					root.classList.add(theme)
+					root.style.colorScheme = theme
+				} catch {}
+			})()
+		</script>
+	</head>
+	<body>
+		<div id="app"></div>
+		<script type="module" src="/src/entry.ts"></script>
+	</body>
+</html>

apps/local-ui-foldkit/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@maple/local-ui-foldkit",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"dev": "vite dev --port ${PORT:-4329} --host ${HOST:-127.0.0.1}",
+		"build": "vite build",
+		"test": "vitest run --passWithNoTests",
+		"typecheck": "tsrs --noEmit"
+	},
+	"dependencies": {
+		"@floating-ui/dom": "1.8.0",
+		"@foldkit/ui": "0.168.0",
+		"@fontsource-variable/geist": "^5.3.0",
+		"@fontsource-variable/geist-mono": "^5.3.0",
+		"@maple/domain": "workspace:*",
+		"@maple/local-ui": "workspace:*",
+		"@maple/query-engine": "workspace:*",
+		"@maple/ui": "workspace:*",
+		"@maple/web-foldkit": "workspace:*",
+		"@tanstack/charts": "catalog:charts",
+		"@tanstack/charts-scales": "catalog:charts",
+		"effect": "catalog:effect",
+		"foldkit": "0.168.0",
+		"sugar-high": "^2.5.1"
+	},
+	"devDependencies": {
+		"@effect/language-service": "catalog:effect",
+		"@foldkit/vite-plugin": "0.27.1",
+		"@tailwindcss/vite": "catalog:tailwind",
+		"@types/node": "catalog:tooling",
+		"tailwindcss": "catalog:tailwind",
+		"tw-animate-css": "catalog:tailwind",
+		"typescript": "catalog:tooling",
+		"vite": "catalog:",
+		"vitest": "catalog:"
+	}
+}

apps/local-ui-foldkit/src/command.ts

@@ -0,0 +1,100 @@
+import { writeLocalStorage } from "@maple/ui/lib/local-storage"
+import { Clock, Duration, Effect, Schema } from "effect"
+import { Command } from "foldkit"
+import { load, pushUrl, replaceUrl } from "foldkit/navigation"
+import { fetchSignalPresence, PRESENCE_STALE_MS } from "./data/signal-presence"
+import { RANGE_STORAGE_KEY, Theme } from "./env"
+import { Message } from "./message"
+import { probeServer } from "./server/probe"
+
+/** `navigate(path, query, { replace })`: page moves push, in-place filter tweaks replace. */
+export const Navigate = Command.define("NavigateLocal", {
+	args: { hash: Schema.String, isReplace: Schema.Boolean },
+	messages: [Message.CompletedNavigate],
+	execute: ({ hash, isReplace }) =>
+		(isReplace ? replaceUrl(hash) : pushUrl(hash)).pipe(Effect.as(Message.CompletedNavigate())),
+})
+
+/** A link to another origin (docs) is a full navigation. */
+export const LoadExternal = Command.define("LoadLocalExternal", {
+	args: { href: Schema.String },
+	messages: [Message.CompletedNavigate],
+	execute: ({ href }) => load(href).pipe(Effect.as(Message.CompletedNavigate())),
+})
+
+/** `goBack`: history back within the app. */
+export const GoBack = Command.define("GoBackLocal", {
+	messages: [Message.CompletedNavigate],
+	execute: Effect.sync(() => {
+		history.back()
+		return Message.CompletedNavigate()
+	}),
+})
+
+export const RememberRange = Command.define("RememberLocalRange", {
+	args: { range: Schema.String },
+	messages: [Message.CompletedRememberRange],
+	execute: ({ range }) =>
+		Effect.sync(() => {
+			writeLocalStorage(RANGE_STORAGE_KEY, range)
+			return Message.CompletedRememberRange()
+		}),
+})
+
+export const ProbeServer = Command.define("ProbeLocalServer", {
+	args: { apiBase: Schema.String },
+	messages: [Message.CompletedProbeServer],
+	execute: ({ apiBase }) =>
+		Effect.gen(function* () {
+			const outcome = yield* probeServer(apiBase)
+			const checkedAtMs = yield* Clock.currentTimeMillis
+			return Message.CompletedProbeServer({ outcome, checkedAtMs })
+		}),
+})
+
+/** `useSignalPresence`: a read younger than `staleTime` is reused, else the store is asked again. */
+export const FetchSignalPresence = Command.define("FetchLocalSignalPresence", {
+	args: { apiBase: Schema.String, lastReadAtMs: Schema.NullOr(Schema.Number) },
+	messages: [Message.SucceededFetchSignalPresence, Message.FailedFetchSignalPresence, Message.ReusedSignalPresence],
+	execute: ({ apiBase, lastReadAtMs }) =>
+		Effect.gen(function* () {
+			const nowMs = yield* Clock.currentTimeMillis
+			if (lastReadAtMs !== null && nowMs - lastReadAtMs < PRESENCE_STALE_MS) return Message.ReusedSignalPresence()
+			return yield* fetchSignalPresence(apiBase).pipe(
+				Effect.map((result) => Message.SucceededFetchSignalPresence({ result })),
+				Effect.catch((failure) => Effect.succeed(Message.FailedFetchSignalPresence({ failure }))),
+			)
+		}),
+})
+
+/** Apply the OS theme the way `setTheme(theme, { persist: false })` does. */
+export const ApplyTheme = Command.define("ApplyLocalTheme", {
+	args: { theme: Theme },
+	messages: [Message.CompletedApplyTheme],
+	execute: ({ theme }) =>
+		Effect.sync(() => {
+			const root = document.documentElement
+			root.classList.remove("light", "dark")
+			root.classList.add(theme)
+			root.style.colorScheme = theme
+			return Message.CompletedApplyTheme()
+		}),
+})
+
+/** `SidebarProvider` keeps the open state in a cookie for a week. */
+export const SaveSidebarState = Command.define("SaveLocalSidebarState", {
+	args: { isOpen: Schema.Boolean },
+	messages: [Message.CompletedSaveSidebarState],
+	execute: ({ isOpen }) =>
+		Effect.sync(() => {
+			document.cookie = `sidebar_state=${String(isOpen)}; path=/; max-age=${60 * 60 * 24 * 7}`
+			return Message.CompletedSaveSidebarState()
+		}),
+})
+
+export const WaitBeforeProbe =Command.define("WaitBeforeLocalProbe", {
+	args: { version: Schema.Number, delayMs: Schema.Number },
+	messages: [Message.ElapsedProbeDelay],
+	execute: ({ version, delayMs }) =>
+		Effect.as(Effect.sleep(Duration.millis(delayMs)), Message.ElapsedProbeDelay({ version })),
+})

apps/local-ui-foldkit/src/data/cache-store.test.ts

@@ -0,0 +1,50 @@
+import { DateTime, Option } from "effect"
+import { describe, expect, test } from "vitest"
+import { type CacheEntry, type CacheValue, hashKey, MAX_AGE_MS, newestOlderWindow, parseSaved, serialize } from "./cache-store"
+
+const NOW = Date.parse("2026-10-01T12:00:00Z")
+const entry = (key: ReadonlyArray<unknown>, updatedAtMs: number, data: CacheValue = []): CacheEntry => ({ key, data, updatedAtMs })
+const mapOf = (...entries: ReadonlyArray<CacheEntry>) => new Map(entries.map((item) => [hashKey(item.key), item]))
+
+describe("hashKey", () => {
+	test("ignores object key order and undefined fields, like React Query", () => {
+		expect(hashKey(["local", { b: 1, a: undefined, c: "x" }])).toBe(hashKey(["local", { c: "x", b: 1 }]))
+	})
+})
+
+describe("newestOlderWindow", () => {
+	const filters = { errorsOnly: false }
+	const current = ["local", "traces", filters, "2026-10-01 11:00:00/2026-10-01 12:00:00"]
+
+	test("picks the newest earlier window of the same length for the same view", () => {
+		const older = entry(["local", "traces", filters, "2026-10-01 09:00:00/2026-10-01 10:00:00"], NOW - 7_200_000)
+		const newer = entry(["local", "traces", filters, "2026-10-01 10:00:00/2026-10-01 11:00:00"], NOW - 3_600_000)
+		expect(newestOlderWindow(mapOf(older, newer), current)).toEqual(Option.some(newer))
+	})
+
+	test("skips other views, other lengths and later windows", () => {
+		const otherFilters = entry(["local", "traces", { errorsOnly: true }, "2026-10-01 10:00:00/2026-10-01 11:00:00"], NOW)
+		const longer = entry(["local", "traces", filters, "2026-10-01 05:00:00/2026-10-01 11:00:00"], NOW)
+		const later = entry(["local", "traces", filters, "2026-10-01 11:30:00/2026-10-01 12:30:00"], NOW)
+		expect(newestOlderWindow(mapOf(otherFilters, longer, later), current)).toEqual(Option.none())
+	})
+
+	test("a key without a window has no stand-in", () => {
+		expect(newestOlderWindow(mapOf(entry(["local", "trace", "a"], NOW)), ["local", "trace", "b"])).toEqual(Option.none())
+	})
+})
+
+describe("saved form", () => {
+	test("round-trips Effect values and drops entries older than a day", () => {
+		const startTime = DateTime.makeUnsafe(NOW - 1_000)
+		const fresh = entry(["local", "trace", "t1"], NOW - 60_000, { rows: [{ startTime, maybe: Option.some(1) }] })
+		const stale = entry(["local", "trace", "t2"], NOW - MAX_AGE_MS - 1)
+		const restored = parseSaved(serialize(mapOf(fresh, stale)), NOW)
+		expect([...restored.keys()]).toEqual([hashKey(fresh.key)])
+		expect(restored.get(hashKey(fresh.key))?.data).toEqual(fresh.data)
+	})
+
+	test("unreadable text restores nothing", () => {
+		expect(parseSaved("{not json", NOW).size).toBe(0)
+	})
+})