frontier-os-app-builder 1.0.0 → 1.2.0

package/templates/app/layout-standalone.tsx

@@ -0,0 +1,8 @@
+import { Outlet } from 'react-router-dom';
+import { FrontierServicesProvider } from '../lib/frontier-services';
+
+export const Layout = () => (
+  <FrontierServicesProvider>
+    <Outlet />
+  </FrontierServicesProvider>
+);

package/templates/app/layout.tsx

@@ -1,21 +1,27 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState, type ReactNode } from 'react';
 import { Outlet } from 'react-router-dom';
 import { isInFrontierApp, createStandaloneHTML } from '@frontiertower/frontier-sdk/ui-utils';
-import { SdkProvider } from '../lib/sdk-context';
+import { SdkProvider, useSdk } from '../lib/sdk-context';
+import { FrontierServicesProvider } from '../lib/frontier-services';
+import { createSdkServices } from '../lib/sdk-services';
+
+// Bridges the live SDK (from SdkProvider) into the FrontierServices seam that
+// feature code consumes via useServices(). Keeps feature code SDK-agnostic: the
+// exact same components run against mocks (standalone) and the real SDK (iframe).
+const SdkServicesBridge = ({ children }: { children: ReactNode }) => {
+  const sdk = useSdk();
+  const services = useMemo(() => createSdkServices(sdk), [sdk]);
+  return <FrontierServicesProvider services={services}>{children}</FrontierServicesProvider>;
+};
 
 export const Layout = () => {
   const [loading, setLoading] = useState(true);
   const [standaloneHtml, setStandaloneHtml] = useState('');
 
   useEffect(() => {
-    const inFrontier = isInFrontierApp();
-
-    if (!inFrontier) {
+    if (!isInFrontierApp()) {
       setStandaloneHtml(createStandaloneHTML('{{APP_NAME}}'));
-      setLoading(false);
-      return;
     }
-
     setLoading(false);
   }, []);
 
@@ -37,9 +43,13 @@ export const Layout = () => {
     );
   }
 
+  // In-frame: provide both the raw SDK (useSdk) and the SDK-backed services
+  // seam (useServices) so every feature component works unchanged from standalone.
   return (
     <SdkProvider>
-      <Outlet />
+      <SdkServicesBridge>
+        <Outlet />
+      </SdkServicesBridge>
     </SdkProvider>
   );
 };

package/templates/app/package-standalone.json

@@ -0,0 +1,35 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview",
+    "lint": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-icons": "^5.5.0",
+    "react-router-dom": "^7.12.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.1.18",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "jsdom": "^27.4.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
+  }
+}

package/templates/app/package.json

@@ -15,7 +15,8 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-icons": "^5.5.0",
-    "react-router-dom": "^7.12.0"
+    "react-router-dom": "^7.12.0",
+    "viem": "^2.44.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.18",

package/templates/app/public/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" role="img" aria-label="Frontier">
+  <circle cx="16" cy="16" r="14" fill="#764AE2" />
+</svg>

package/templates/app/sdk-context.tsx

@@ -1,4 +1,4 @@
-import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from 'react';
+import { createContext, useContext, useEffect, useState, type ReactNode } from 'react';
 import { FrontierSDK } from '@frontiertower/frontier-sdk';
 
 const SdkContext = createContext<FrontierSDK | null>(null);
@@ -10,23 +10,21 @@ export const useSdk = (): FrontierSDK => {
 };
 
 export const SdkProvider = ({ children }: { children: ReactNode }) => {
-  const sdkRef = useRef<FrontierSDK | null>(null);
-  const [ready, setReady] = useState(false);
+  const [sdk, setSdk] = useState<FrontierSDK | null>(null);
 
   useEffect(() => {
-    const sdk = new FrontierSDK();
-    sdkRef.current = sdk;
-    setReady(true);
+    const instance = new FrontierSDK();
+    setSdk(instance);
 
     return () => {
-      sdk.destroy();
+      instance.destroy();
     };
   }, []);
 
-  if (!ready) return null;
+  if (!sdk) return null;
 
   return (
-    <SdkContext.Provider value={sdkRef.current}>
+    <SdkContext.Provider value={sdk}>
       {children}
     </SdkContext.Provider>
   );

package/templates/app/sdk-services.tsx

@@ -0,0 +1,98 @@
+/**
+ * SDK Services Adapter
+ *
+ * Maps the FrontierServices interface to real SDK module calls.
+ * Used when the app runs inside the Frontier OS iframe.
+ * Only modules declared in manifest.json are wired; unused modules throw.
+ *
+ * During SDK Integration the executor should:
+ * 1. Wire modules the app actually uses (replace Proxy stubs with real SDK calls)
+ * 2. Keep Proxy stubs for unused modules
+ */
+
+import type { FrontierSDK } from '@frontiertower/frontier-sdk';
+import type {
+  FrontierServices,
+  WalletService,
+  StorageService,
+  ChainService,
+  UserService,
+  PartnershipsService,
+  ThirdPartyService,
+  CommunitiesService,
+  EventsService,
+  OfficesService,
+  NavigationService,
+} from './frontier-services';
+
+function notAvailable(module: string): never {
+  throw new Error(`[SDK] ${module} module is not available in this app`);
+}
+
+export function createSdkServices(sdk: FrontierSDK): FrontierServices {
+  void sdk; // marks `sdk` used while modules are still stubs; remove once you wire one below (e.g. sdk.getWallet())
+  // ── Wire modules your app uses ──────────────────────────────
+  // Replace the Proxy stubs below with real SDK adapter objects
+  // for each module declared in manifest.json.
+  //
+  // Example (wallet):
+  //   const walletAccess = sdk.getWallet();
+  //   const wallet: WalletService = {
+  //     getBalance: () => walletAccess.getBalance(),
+  //     ...
+  //   };
+
+  // ── Stub modules not used by this app ───────────────────────
+  const wallet = new Proxy({} as WalletService, {
+    get: () => () => notAvailable('Wallet'),
+  });
+
+  const storage = new Proxy({} as StorageService, {
+    get: () => () => notAvailable('Storage'),
+  });
+
+  const chain = new Proxy({} as ChainService, {
+    get: () => () => notAvailable('Chain'),
+  });
+
+  const user = new Proxy({} as UserService, {
+    get: () => () => notAvailable('User'),
+  });
+
+  const partnerships = new Proxy({} as PartnershipsService, {
+    get: () => () => notAvailable('Partnerships'),
+  });
+
+  const thirdParty = new Proxy({} as ThirdPartyService, {
+    get: () => () => notAvailable('ThirdParty'),
+  });
+
+  const communities = new Proxy({} as CommunitiesService, {
+    get: () => () => notAvailable('Communities'),
+  });
+
+  const events = new Proxy({} as EventsService, {
+    get: () => () => notAvailable('Events'),
+  });
+
+  const offices = new Proxy({} as OfficesService, {
+    get: () => () => notAvailable('Offices'),
+  });
+
+  const navigation = new Proxy({} as NavigationService, {
+    get: () => () => notAvailable('Navigation'),
+  });
+
+  return {
+    wallet,
+    storage,
+    chain,
+    user,
+    partnerships,
+    thirdParty,
+    communities,
+    events,
+    offices,
+    navigation,
+  };
+}

package/templates/app/vercel-standalone.json

@@ -0,0 +1,5 @@
+{
+  "rewrites": [
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}

package/templates/app/vercel.json

@@ -5,13 +5,6 @@
   "headers": [
     {
       "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://os.frontiertower.io"
-        }
-      ],
       "headers": [
         {
           "key": "Access-Control-Allow-Origin",
@@ -24,102 +17,22 @@
         {
           "key": "Access-Control-Allow-Headers",
           "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://alpha.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://alpha.os.frontiertower.io"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Content-Security-Policy",
+          "value": "frame-ancestors https://os.frontiertower.io https://sandbox.os.frontiertower.io http://localhost:5173;"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://beta.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://beta.os.frontiertower.io"
+          "key": "X-Content-Type-Options",
+          "value": "nosniff"
         },
         {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
+          "key": "Referrer-Policy",
+          "value": "strict-origin-when-cross-origin"
         },
         {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "https://sandbox.os.frontiertower.io"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "https://sandbox.os.frontiertower.io"
-        },
-        {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
-        },
-        {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
-        }
-      ]
-    },
-    {
-      "source": "/(.*)",
-      "has": [
-        {
-          "type": "header",
-          "key": "Origin",
-          "value": "http://localhost:5173"
-        }
-      ],
-      "headers": [
-        {
-          "key": "Access-Control-Allow-Origin",
-          "value": "http://localhost:5173"
-        },
-        {
-          "key": "Access-Control-Allow-Methods",
-          "value": "GET, OPTIONS"
-        },
-        {
-          "key": "Access-Control-Allow-Headers",
-          "value": "Content-Type"
+          "key": "Permissions-Policy",
+          "value": "camera=(), microphone=(), geolocation=()"
         }
       ]
     }

package/templates/state/plan.md

@@ -42,8 +42,9 @@ SDK Modules: [Which SDK modules are used in this plan, if any]
 @.frontier-app/ROADMAP.md
 @.frontier-app/STATE.md
 
-# SDK reference for modules used in this plan:
-@frontier-sdk/docs/[module].md
+# Feature phases consume the mock service layer (useServices) — no SDK docs in <context>.
+# SDK module docs are referenced ONLY in the final SDK Integration plan, via:
+# @frontier-os-app-builder/references/sdk/[module].md
 
 # Only reference prior plan SUMMARYs if genuinely needed:
 # - This plan uses types/exports from prior plan
@@ -88,7 +89,7 @@ SDK Modules: [Which SDK modules are used in this plan, if any]
   <how-to-verify>Visit http://localhost:{{DEV_PORT}} and verify:
   - [Visual check 1]
   - [Visual check 2]
-  Open Frontier OS at localhost:3000 and verify app loads in iframe.</how-to-verify>
+  (SDK Integration phase only) Open Frontier OS at localhost:3000 and verify the app loads in the iframe.</how-to-verify>
   <resume-signal>Type "approved" or describe issues</resume-signal>
 </task>
 
@@ -136,26 +137,43 @@ After completion, create `.frontier-app/phases/XX-name/{phase}-{plan}-SUMMARY.md
 
 ## Frontier OS Specifics
 
-**Phase 1 plans always include:**
+**Phase 1 (scaffold) plans always include — standalone-first:**
 - Vite scaffold from `templates/app/vite.config.ts`
-- SdkProvider from `templates/app/sdk-context.tsx`
-- Layout with iframe detection from `templates/app/layout.tsx`
-- Dark theme setup via Tailwind
-- Standalone fallback UI
+- `FrontierServicesProvider` + mock services from `templates/app/frontier-services.tsx` → `src/lib/frontier-services.tsx` (feature code calls `useServices()`)
+- Layout from `templates/app/layout-standalone.tsx` → `src/views/Layout.tsx` (NO iframe detection, NO SdkProvider)
+- Entry from `templates/app/main-router.tsx` (router entry — all apps use the router)
+- Dark theme via Tailwind 4 `@theme` in `src/styles/index.css` (CSS-only — no `tailwind.config`)
+- Standalone UI rendering with mock data
 - Dev server on assigned port
 
-**SDK usage in tasks:**
-- Always specify the exact import: `import { FrontierSDK } from '@frontiertower/frontier-sdk'`
-- Always use `useSdk()` hook, never instantiate SDK directly in components
-- Always wrap SDK calls in try/catch — SDK may not be available in standalone mode
-- Reference the specific SDK module docs in `<context>` section
+**Phase 1 BLOCKLIST — NEVER include these in a scaffold plan:**
+- ❌ `sdk-context.tsx` — this file is created during SDK Integration phase, NOT Phase 1
+- ❌ `layout.tsx` template — use `layout-standalone.tsx` instead (no iframe detection, no SdkProvider)
+- ❌ single-component entries — use `main-router.tsx` instead (all apps use the router; no single-component entry)
+- ❌ `package.json` template — use `package-standalone.json` instead (no SDK dependency)
+- ❌ `vercel.json` template — use `vercel-standalone.json` instead (no CORS headers)
+- ❌ `@frontiertower/frontier-sdk` in dependencies — SDK is added during SDK Integration phase
+- ❌ `isInFrontierApp()` or `createStandaloneHTML()` in Layout — these are SDK Integration concerns
+- ❌ `SdkProvider` wrapping — use `FrontierServicesProvider` instead
+- ❌ `useSdk()` — use `useServices()` instead
+- ❌ Any import from `@frontiertower/frontier-sdk` — the SDK package does not exist in Phase 1
+
+**Service usage in feature phases (Phase 2+):**
+- Call service methods through the mock seam: `services.<module>.<method>()` (e.g. `services.wallet.getBalance()`)
+- Always obtain services via `useServices()` — `import { useServices } from '../lib/frontier-services'`
+- Wrap service calls in try/catch and handle loading/error states
+- Never import `@frontiertower/frontier-sdk` or call `useSdk()` in feature code
+- The `FrontierSDK` import + `useSdk()` pattern belongs ONLY to the final SDK Integration phase
 
 **Verification always includes:**
 - Build succeeds (`npm run build`)
 - Dev server starts on correct port
 - No TypeScript errors
 - Dark theme renders correctly (no white backgrounds)
-- App works in both iframe and standalone modes
+- Standalone renders with mock services (`useServices()` resolves)
+
+**SDK Integration tier (final phase) additionally verifies:**
+- App works in both iframe and standalone modes (in-frame `services.*` resolve via the SDK bridge)
 
 ---
 

package/templates/state/requirements.md

@@ -87,7 +87,7 @@ Which phases cover which requirements. Updated during roadmap creation.
 
 **Standard Platform Requirements:**
 - PLAT-01 through PLAT-05 are ALWAYS included for every Frontier OS app
-- They always map to Phase 1 (Scaffold + SDK Core)
+- They always map to Phase 1 (Scaffold + Standalone Shell)
 - They are non-negotiable — an app without these cannot run in Frontier OS
 
 **Requirement Format:**

package/templates/state/roadmap.md

@@ -14,27 +14,28 @@ What makes this app worth building and what does the finished product look like?
 
 ## {{MILESTONE_VERSION}} Phases
 
-- [ ] **Phase 1: Scaffold + SDK Core** — Project setup, SdkProvider, iframe detection, dark theme, standalone fallback
+- [ ] **Phase 1: Scaffold + Standalone Shell** — Project setup, services layer, mock data, dark theme
 - [ ] **Phase 2: [Feature Name]** — [One-line description]
 - [ ] **Phase 3: [Feature Name]** — [One-line description]
-- [ ] **Phase N: [Feature Name]** — [One-line description]
+- [ ] **Phase N-1: [Feature Name]** — [One-line description]
+- [ ] **Phase N: SDK Integration** — Wire SDK, create adapter, upgrade Layout for iframe
 
 ## Phase Details
 
-### Phase 1: Scaffold + SDK Core
-**Goal**: Working app shell with SDK connected, running in iframe and standalone
+### Phase 1: Scaffold + Standalone Shell
+**Goal**: Working app shell running standalone in browser with mock data
 **Depends on**: Nothing (always first)
 **Requirements**: PLAT-01, PLAT-02, PLAT-03, PLAT-04, PLAT-05
 **Success Criteria** (what must be TRUE):
-  1. App renders inside Frontier OS iframe without errors
-  2. App detects standalone mode and shows appropriate fallback UI
-  3. Dark theme applied — no white backgrounds, no light-mode artifacts
-  4. SdkProvider initializes and useSdk() returns a valid SDK instance
-  5. Dev server runs on assigned port with HMR working
+  1. App renders standalone in browser with mock data
+  2. Dark theme applied — no white backgrounds, no light-mode artifacts
+  3. useServices() returns mock wallet balance, user data, storage
+  4. Dev server runs on assigned port with HMR working
+  5. npm run build succeeds
 **Plans**: 1 plan
 
 Plans:
-- [ ] 01-01: Vite + React scaffold, SdkProvider, iframe detection, dark theme, dev config
+- [ ] 01-01: Vite + React scaffold, services layer, mock data, dark theme, dev config
 
 ### Phase 2: [Feature Name]
 **Goal**: [What this phase delivers — one sentence]
@@ -50,9 +51,9 @@ Plans:
 - [ ] 02-01: [Brief description of first plan]
 - [ ] 02-02: [Brief description of second plan]
 
-### Phase N: [Feature Name]
+### Phase N-1: [Feature Name]
 **Goal**: [What this phase delivers]
-**Depends on**: Phase [N-1]
+**Depends on**: Phase [N-2]
 **Requirements**: [REQ-XX, REQ-YY]
 **Success Criteria** (what must be TRUE):
   1. [Observable behavior from user perspective]
@@ -62,13 +63,30 @@ Plans:
 Plans:
 - [ ] NN-01: [Brief description]
 
+### Phase N: SDK Integration
+**Goal**: Wire real Frontier SDK into the standalone app shell
+**Depends on**: All feature phases
+**Requirements**: PLAT-SDK-01
+**Success Criteria** (what must be TRUE):
+  1. sdk-context.tsx exists and exports useSdk + SdkProvider
+  2. sdk-services.tsx maps all service methods to real SDK calls
+  3. Layout.tsx has isInFrontierApp() detection and SdkProvider wrapping
+  4. vercel.json has CORS + CSP frame-ancestors (3 origins) + security headers
+  5. App works both standalone (mocks) and in iframe (real SDK)
+  6. npm run build succeeds
+**Plans**: 1 plan (mechanical)
+
+Plans:
+- [ ] NN-01: SDK dependency, adapter, Layout upgrade, CORS
+
 ## Progress
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Scaffold + SDK Core | 0/1 | Not started | - |
+| 1. Scaffold + Standalone Shell | 0/1 | Not started | - |
 | 2. [Name] | 0/N | Not started | - |
-| N. [Name] | 0/N | Not started | - |
+| N-1. [Name] | 0/N | Not started | - |
+| N. SDK Integration | 0/1 | Not started | - |
 
 ---
 *Roadmap created: {{DATE}}*
@@ -80,15 +98,22 @@ Plans:
 <guidelines>
 
 **Phase 1 is always the same:**
-- "Scaffold + SDK Core" — never skip, never rename
+- "Scaffold + Standalone Shell" — never skip, never rename
 - Covers all PLAT-* requirements
 - Always 1 plan (the scaffold is well-defined)
 - Success criteria are standardized (see template)
-- Uses templates from `templates/app/` directory
+- Uses standalone templates from `templates/app/` directory (frontier-services.tsx, layout-standalone.tsx, package-standalone.json, vercel-standalone.json)
+
+**Final phase is always SDK Integration:**
+- Auto-added as the last phase — never skip, never rename
+- Always 1 plan (mechanical, no user decisions)
+- Wires real SDK: adds dependency, creates adapter, upgrades Layout, adds CORS
+- Fixed success criteria (see template)
 
 **Phase structure:**
-- Phase 1: Scaffold (always)
-- Phases 2-N: Feature phases (from requirements)
+- Phase 1: Scaffold + Standalone Shell (always)
+- Phases 2 to N-1: Feature phases (from requirements)
+- Phase N: SDK Integration (always last)
 - Keep to 3-6 total phases for v1 — ship fast
 - Each phase delivers something coherent and testable
 
@@ -113,17 +138,25 @@ Plans:
 
 <frontier_specifics>
 
-**Phase 1 always generates from templates:**
+**Phase 1 always generates from standalone templates:**
 - `templates/app/vite.config.ts` → configured with app's dev port
-- `templates/app/sdk-context.tsx` → SdkProvider + useSdk hook
-- `templates/app/layout.tsx` → dark theme shell with iframe detection
-- `templates/app/main-simple.tsx` or `main-router.tsx` → entry point
+- `templates/app/frontier-services.tsx` → useServices() provider + mock services
+- `templates/app/layout-standalone.tsx` → dark theme shell with FrontierServicesProvider
+- `templates/app/main-router.tsx` → entry point
+- `templates/app/package-standalone.json` → dependencies without SDK
+- `templates/app/vercel-standalone.json` → SPA rewrite only (no CORS)
 - `templates/app/tsconfig.json` → TypeScript config
 - `templates/app/postcss.config.js` → Tailwind setup
 
-**Feature phases should reference SDK modules:**
+**Feature phases should reference service modules:**
 - If a phase uses Events module, note it in the goal
 - If a phase uses Wallet module, note it in the goal
-- This helps the planner know which SDK APIs to use
+- This helps the planner know which service methods to use via useServices()
+
+**SDK Integration phase generates from SDK templates:**
+- `templates/app/sdk-context.tsx` → SdkProvider + useSdk hook
+- `templates/app/sdk-services.tsx` → adapter mapping services to real SDK
+- `templates/app/layout.tsx` → Layout upgrade with iframe detection
+- `templates/app/vercel.json` → full CORS origins
 
 </frontier_specifics>