feat: URL-addressable preview with suffix-based routing (#426)

Author: BlueHotDog

.changeset/url-addressable-preview.md

@@ -0,0 +1,9 @@
+---
+"@frontman/frontman-core": minor
+"@frontman-ai/astro": minor
+"@frontman-ai/vite": minor
+"@frontman-ai/nextjs": minor
+"@frontman/client": minor
+---
+
+URL-addressable preview: persist iframe URL in browser address bar using suffix-based routing. Navigation within the preview iframe is now reflected in the browser URL, enabling shareable deep links and browser back/forward support.

apps/frontman_server/config/runtime.exs

@@ -27,11 +27,6 @@ if config_env() in [:dev, :test] do
     openai_api_key: env!("OPENAI_API_KEY", :string, nil)
 end
 
-# Discord webhook for #new-users signup alerts
-config :frontman_server,
-  discord_new_users_webhook_url: env!("DISCORD_NEW_USERS_WEBHOOK_URL", :string!),
-  discord_pg_channel: "new_user"
-
 # WorkOS configuration for OAuth (GitHub, Google)
 config :workos, WorkOS.Client,
   api_key: env!("WORKOS_API_KEY", :string, nil),
@@ -91,6 +86,10 @@ if config_env() in [:dev, :test] do
 end
 
 if config_env() == :prod do
+  config :frontman_server,
+    discord_new_users_webhook_url: env!("DISCORD_NEW_USERS_WEBHOOK_URL", :string!),
+    discord_pg_channel: "new_user"
+
   config :sentry,
     dsn:
       "https://442ae992e5a5ccfc42e6910220aeb2a9@o4510512511320064.ingest.de.sentry.io/4510512546185296",

apps/frontman_server/envs/.test.env

@@ -4,4 +4,3 @@ GOOGLE_API_KEY=test-google-key
 XAI_API_KEY=test-xai-key
 OPENROUTER_API_KEY=test-openrouter-key
 REQ_LLM_FIXTURES_MODE=replay
-DISCORD_NEW_USERS_WEBHOOK_URL=https://discord.com/api/webhooks/test/test

apps/frontman_server/lib/frontman_server/application.ex

@@ -32,6 +32,20 @@ defmodule FrontmanServer.Application do
       nil
     )
 
+    # Discord new-user signup alerts (PG LISTEN/NOTIFY → webhook) – prod only
+    discord_children =
+      if Application.get_env(:frontman_server, :discord_new_users_webhook_url) do
+        [
+          {Postgrex.Notifications, [name: FrontmanServer.PGNotifications] ++ pg_notify_opts()},
+          {FrontmanServer.Notifications.Discord,
+           webhook_url: Application.get_env(:frontman_server, :discord_new_users_webhook_url),
+           channel: Application.get_env(:frontman_server, :discord_pg_channel),
+           notifications_pid: FrontmanServer.PGNotifications}
+        ]
+      else
+        []
+      end
+
     children =
       [
         FrontmanServerWeb.Telemetry,
@@ -46,14 +60,8 @@ defmodule FrontmanServer.Application do
         # TaskSupervisor for agent execution tasks
         {Task.Supervisor, name: FrontmanServer.TaskSupervisor},
         # Start to serve requests, typically the last entry
-        FrontmanServerWeb.Endpoint,
-        # Discord new-user signup alerts (PG LISTEN/NOTIFY → webhook)
-        {Postgrex.Notifications, [name: FrontmanServer.PGNotifications] ++ pg_notify_opts()},
-        {FrontmanServer.Notifications.Discord,
-         webhook_url: Application.get_env(:frontman_server, :discord_new_users_webhook_url),
-         channel: Application.get_env(:frontman_server, :discord_pg_channel),
-         notifications_pid: FrontmanServer.PGNotifications}
-      ]
+        FrontmanServerWeb.Endpoint
+      ] ++ discord_children
 
     # See https://hexdocs.pm/elixir/Supervisor.html
     # for other strategies and supported options

libs/bindings/src/Astro.res

@@ -24,6 +24,24 @@ type astroConfig = {
 // Vite plugin type — opaque, we just pass plugin objects through
 type vitePlugin
 
+// Vite dev server connect middleware stack
+type connectMiddlewareStack
+
+@send
+external use: (connectMiddlewareStack, NodeHttp.connectMiddleware) => unit = "use"
+
+// Vite dev server (minimal bindings for astro:server:setup)
+type viteDevServer = {middlewares: connectMiddlewareStack}
+
+// Config for constructing a Vite plugin with typed fields we use.
+// Keeps vitePlugin opaque while avoiding Obj.magic at call sites.
+type vitePluginConfig = {
+  name: string,
+  configureServer?: viteDevServer => unit,
+}
+
+external makeVitePlugin: vitePluginConfig => vitePlugin = "%identity"
+
 // Partial Astro config for updateConfig — only the fields we need
 type partialViteConfig = {plugins?: array<vitePlugin>}
 type partialAstroConfig = {vite?: partialViteConfig}
@@ -38,15 +56,6 @@ type configSetupHookContext = {
   command: astroCommand,
 }
 
-// Vite dev server connect middleware stack
-type connectMiddlewareStack
-
-@send
-external use: (connectMiddlewareStack, NodeHttp.connectMiddleware) => unit = "use"
-
-// Vite dev server (minimal bindings for astro:server:setup)
-type viteDevServer = {middlewares: connectMiddlewareStack}
-
 // --- Server-side toolbar object (available in astro:server:setup hook) ---
 // Must be defined before serverSetupHookContext which references it.
 

libs/bindings/src/LocalStorage.res

@@ -0,0 +1,16 @@
+// Bindings for the Web Storage API (localStorage)
+
+@val @scope("localStorage")
+external getItem: string => Nullable.t<string> = "getItem"
+
+@val @scope("localStorage")
+external setItem: (string, string) => unit = "setItem"
+
+@val @scope("localStorage")
+external removeItem: string => unit = "removeItem"
+
+@val @scope("localStorage")
+external key: int => Nullable.t<string> = "key"
+
+@val @scope("localStorage")
+external length: int = "length"

libs/bindings/src/MutationObserver.res

@@ -0,0 +1,28 @@
+type t
+
+type mutationRecord = {
+  @as("type") type_: string,
+  target: WebAPI.DOMAPI.node,
+  addedNodes: array<WebAPI.DOMAPI.node>,
+  removedNodes: array<WebAPI.DOMAPI.node>,
+  attributeName: Null.t<string>,
+  oldValue: Null.t<string>,
+}
+
+type observeOptions = {
+  "childList": bool,
+  "attributes": bool,
+  "characterData": bool,
+  "subtree": bool,
+  "attributeOldValue": bool,
+  "characterDataOldValue": bool,
+}
+
+@new
+external make: (array<mutationRecord> => unit) => t = "MutationObserver"
+
+@send
+external observe: (t, WebAPI.DOMAPI.node, observeOptions) => unit = "observe"
+
+@send
+external disconnect: t => unit = "disconnect"

libs/bindings/src/NavigateEvent.res

@@ -0,0 +1,6 @@
+type destination
+
+type t
+
+@get external destination: t => destination = "destination"
+@get external url: destination => string = "url"

libs/client/src/Client__FtueState.res

@@ -16,18 +16,13 @@ type t =
   | WelcomeShown
   | Completed
 
-@val @scope("localStorage") external getItem: string => Nullable.t<string> = "getItem"
-@val @scope("localStorage") external setItem: (string, string) => unit = "setItem"
-@val @scope("localStorage") external localStorageKey: (int) => Nullable.t<string> = "key"
-@val @scope("localStorage") external localStorageLength: int = "length"
-
 // Check whether any other frontman:* localStorage key exists, indicating a returning user
 let hasExistingFrontmanData = (): bool => {
   try {
-    let len = localStorageLength
+    let len = FrontmanBindings.LocalStorage.length
     let found = ref(false)
     for i in 0 to len - 1 {
-      switch localStorageKey(i)->Nullable.toOption {
+      switch FrontmanBindings.LocalStorage.key(i)->Nullable.toOption {
       | Some(k) =>
         switch k->String.startsWith("frontman:") && k !== storageKey {
         | true => found := true
@@ -44,15 +39,15 @@ let hasExistingFrontmanData = (): bool => {
 
 let get = (): t => {
   try {
-    switch getItem(storageKey)->Nullable.toOption {
+    switch FrontmanBindings.LocalStorage.getItem(storageKey)->Nullable.toOption {
     | Some("welcome_shown") => WelcomeShown
     | Some("completed") => Completed
     | Some(_) | None =>
       // No FTUE key — check if user is truly new or an existing user who predates FTUE
       switch hasExistingFrontmanData() {
       | true =>
         // Auto-migrate existing user: write Completed so this check only runs once
-        setItem(storageKey, "completed")
+        FrontmanBindings.LocalStorage.setItem(storageKey, "completed")
         Completed
       | false => New
       }
@@ -63,9 +58,9 @@ let get = (): t => {
 }
 
 let setWelcomeShown = () => {
-  setItem(storageKey, "welcome_shown")
+  FrontmanBindings.LocalStorage.setItem(storageKey, "welcome_shown")
 }
 
 let setCompleted = () => {
-  setItem(storageKey, "completed")
+  FrontmanBindings.LocalStorage.setItem(storageKey, "completed")
 }