WIP: 🛝 Playground

.gitignore

@@ -3,9 +3,10 @@ shared/dist
 .env
 .envrc
 
-# To make my life temporarily easier
+# temp for my branch
 lilo/lilo-worker/.prod.vars
 lilo/lilo-worker/.dev.vars
+remove_node_modules.sh
 
 # Cursor
 .cursorrules

api/package.json

@@ -43,6 +43,7 @@
     "@ai-sdk/mistral": "^1.0.3",
     "@ai-sdk/openai": "^1.0.5",
     "@fiberplane/fpx-types": "workspace:*",
+    "@fiberplane/embedded": "workspace:*",
     "@fiberplane/source-analysis": "workspace:*",
     "@hono/node-server": "^1.13.7",
     "@hono/zod-validator": "^0.4.1",

api/src/app.ts

@@ -7,6 +7,7 @@ import type * as schema from "./db/schema.js";
 import type { Bindings, Variables } from "./lib/types.js";
 import logger from "./logger/index.js";
 
+import { createMiddleware } from "@fiberplane/embedded";
 import { HTTPException } from "hono/http-exception";
 import type * as webhoncType from "./lib/webhonc/index.js";
 import appRoutes from "./routes/app-routes.js";
@@ -73,5 +74,12 @@ export function createApp(
   app.route("/", settings);
   app.route("/", collections);
 
+  app.use(
+    "/fp/*",
+    createMiddleware({
+      apiKey: "1234",
+    }),
+  );
+
   return app;
 }

biome.jsonc

@@ -41,7 +41,7 @@
       }
     },
     {
-      "include": ["studio", "lilo/lilo-frontend"],
+      "include": ["studio", "lilo/lilo-frontend", "playground"],
       "linter": {
         "enabled": true,
         "rules": {
@@ -109,6 +109,8 @@
       ".astro",
       // ignore all tsconfig.json files
       "tsconfig*.json",
+      // ignore the autogenerated routeTree.gen.ts file
+      "playground/src/routeTree.gen.ts",
       // ignore any test data files
       "test-data/*.js",
       // fpx-workers build files

lilo/lilo-worker/package.json

@@ -22,7 +22,7 @@
   "dependencies": {
     "@ai-sdk/google": "^1.0.9",
     "@ai-sdk/openai": "^1.0.8",
-    "@fiberplane/embedded": "^0.0.9",
+    "@fiberplane/embedded": "^0.0.17",
     "@hono/oauth-providers": "^0.6.2",
     "@hono/zod-openapi": "^0.18.0",
     "@hono/zod-validator": "^0.4.1",

lilo/lilo-worker/src/index.tsx

@@ -42,34 +42,43 @@ app.doc("/doc", (c) => ({
   ],
 }));
 
+// Mount the Fiberplane playground to play with the API
 // Mount the Fiberplane playground to play with the API
 app.use(
   "/fp/*",
   createMiddleware({
-    cdn: "https://cdn.jsdelivr.net/npm/@fiberplane/embedded/dist/playground/",
-    // @ts-expect-error - The imported spec does not match our expected OpenAPIv3 type
-    spec: app.getOpenAPIDocument({
-      openapi: "3.0.0",
-      info: {
-        title: "Lilo API",
-        version: "0.0.1",
-        description: "API documentation for Lilo",
-      },
-      servers: [
-        {
-          // url: new URL(c.req.url).origin,
-          url: "http://localhost:6246",
-          description: "Local",
-        },
-        {
-          // url: new URL(c.req.url).origin,
-          url: "https://lilo.fp.dev",
-          description: "Production",
-        },
-      ],
-    }),
+    apiKey: "12345",
+    spec: "/doc",
   }),
 );
+// app.use(
+//   "/fp/*",
+//   createMiddleware({
+//     // @ts-expect-error - The imported spec does not match our expected OpenAPIv3 type
+//     spec: app.getOpenAPIDocument({
+//       openapi: "3.0.0",
+//       info: {
+//         title: "Lilo API",
+//         version: "0.0.1",
+//         description: "API documentation for Lilo",
+//       },
+//       servers: [
+//         // NOTE - Embedded should add the current origin automatically.
+//         //
+//         // {
+//         //   // url: new URL(c.req.url).origin,
+//         //   url: "http://localhost:6246",
+//         //   description: "Local",
+//         // },
+//         {
+//           // url: new URL(c.req.url).origin,
+//           url: "https://lilo.fp.dev",
+//           description: "Production",
+//         },
+//       ],
+//     }),
+//   }),
+// );
 
 app.route("/reference", apiReferenceRouter);
 

package.json

@@ -5,6 +5,7 @@
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "postinstall": "pnpm run build:types && pnpm run build:source-analysis",
+    "build:embedded": "pnpm --filter @fiberplane/playground build && rimraf packages/embedded/dist/playground && pnpm --filter @fiberplane/embedded build && cp -r playground/dist packages/embedded/dist/playground",
     "build:types": "pnpm --filter @fiberplane/fpx-types build",
     "build:source-analysis": "pnpm --filter @fiberplane/source-analysis build",
     "build:fpx-studio": "pnpm clean:fpx-studio && pnpm build:api && pnpm build:frontend",

packages/embedded/.gitignore

@@ -0,0 +1 @@
+dist

packages/embedded/.npmignore

@@ -0,0 +1,69 @@
+node_modules
+.dev.vars
+.dev.vars.example
+
+# do not publish source files, even though we point to them in the package.json
+src/
+
+# do not publish biome config
+biome.jsonc
+
+# do not publish migrate typescript file
+migrate.ts
+
+# Change them to your taste:
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+bun.lockb
+
+# mac
+.DS_Store
+
+# dbs
+mizu.db
+mizu.db*
+mizu*.db
+fpx.db
+fpx.db*
+fpx*.db
+.fpxconfig
+.fpxconfig/*
+.fpx
+.fpx/*
+
+# Rust targets
+**/target
+target
+
+.env
+.envrc
+
+# VS Code
+.vscode/*
+*.code-workspace
+
+# CLion
+.idea
+
+# TypeScript / Yarn
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions
+node_modules
+package-lock.json
+yarn-error.log
+
+# Build tools
+.parcel-cache*
+.nx/cache
+*.tsbuildinfo
+
+.git/*
+
+# Personal files
+mizu.boots.code-workspace
+start-dev.sh

packages/embedded/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fiberplane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/embedded/biome.jsonc

@@ -0,0 +1,22 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": ["../../biome.jsonc"],
+  "files": {
+    "ignore": ["dist", "node_modules"]
+  },
+  "overrides": [
+    {
+      "include": ["src"],
+      "linter": {
+        "enabled": true,
+        "rules": {
+          "suspicious": {
+            "noConsoleLog": {
+              "level": "warn"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

packages/embedded/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fiberplane/embedded",
+  "version": "0.0.17",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "license": "MIT or Apache 2",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc",
+    "format": "biome check . --write",
+    "lint": "biome lint .",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "*",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "hono": "^4.6.12",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "hono": "^4.0"
+  },
+  "dependencies": {
+    "openapi-types": "^12.1.3",
+    "zod": "^3.23.8"
+  }
+}

packages/embedded/src/index.ts

@@ -0,0 +1,2 @@
+export { createMiddleware } from "./middleware.js";
+export { FpService } from "./services/index.js";

packages/embedded/src/middleware.ts

@@ -0,0 +1,92 @@
+import type { Context } from "hono";
+import type { Env, MiddlewareHandler } from "hono/types";
+import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
+import { type RouterSpec, createRouter } from "./router.js";
+
+// HACK - We need to manually update the version in the CDN URL when you release a new version
+//        Eventually we should do this automagically when building the package (and derive the version from the package.json)
+const VERSION = "0.0.17";
+const CDN_URL = `https://cdn.jsdelivr.net/npm/@fiberplane/embedded@${VERSION}/dist/playground/`;
+
+export interface EmbeddedMiddlewareOptions {
+  apiKey: string;
+  cdn?: string;
+  spec?: OpenAPIV3_1.Document | OpenAPIV3.Document | string;
+}
+
+export const createMiddleware =
+  <E extends Env>(options: EmbeddedMiddlewareOptions): MiddlewareHandler<E> =>
+  async (c, next) => {
+    const { mountedPath, internalPath } = getPaths(c);
+
+    const origin = new URL(c.req.url).origin;
+    const modSpec: RouterSpec = parseSpecParameter(options?.spec, origin);
+
+    // Forward request to embedded router, continuing middleware chain if no route matches
+    const router = createRouter({
+      ...options,
+      mountedPath,
+      cdn: options?.cdn ?? CDN_URL,
+      spec: modSpec,
+    });
+
+    // Create a new request with the corrected (internal) path
+    const newUrl = new URL(c.req.url);
+    newUrl.pathname = internalPath;
+    const newRequest = new Request(newUrl, c.req.raw);
+    const response = await router.fetch(newRequest);
+
+    // Skip the middleware and continue if the embedded router doesn't match
+    if (response.status === 404) {
+      return next();
+    }
+
+    return response;
+  };
+
+// This middleware is designed to be mounted within another Hono app at any path.
+// Since the parent app determines the mount path, we need to extract and remove
+// this prefix from incoming requests to ensure proper route matching
+function getPaths(c: Context): { mountedPath: string; internalPath: string } {
+  const mountedPath = c.req.routePath.replace("/*", "");
+  const internalPath = c.req.path.replace(mountedPath, "");
+
+  return {
+    mountedPath,
+    internalPath,
+  };
+}
+
+function parseSpecParameter(
+  spec: OpenAPIV3_1.Document | OpenAPIV3.Document | string | undefined,
+  origin: string,
+): RouterSpec {
+  if (!spec) {
+    return {
+      type: "empty",
+      value: undefined,
+      origin,
+    };
+  }
+  if (typeof spec === "string" && spec.startsWith("/")) {
+    return {
+      type: "path",
+      value: spec,
+      origin,
+    };
+  }
+  if (spec && typeof spec === "object") {
+    return {
+      type: "raw",
+      value: spec,
+      origin,
+    };
+  }
+  // NOTE - We assume the spec is a URL if it's not a path-like string or an object
+  // TODO - Make this more robust, add an unknown type
+  return {
+    type: "url",
+    value: spec,
+    origin,
+  };
+}