@frontera-sdk/core 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Sebati
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,42 @@
+# @frontera-sdk/core
+
+The runtime a Frontera app mounts on: the postMessage bridge to the platform
+host, the app bootstrap, and a typed platform client.
+
+```bash
+bun add @frontera-sdk/core react react-dom @tanstack/react-query
+```
+
+```tsx
+import { createFronteraApp } from '@frontera-sdk/core/create-frontera-app'
+
+import App from './App'
+
+createFronteraApp(<App />)
+```
+
+`createFronteraApp` completes the handshake, adopts the host's palette,
+installs the error boundary that reports crashes back to the platform, and only
+then mounts. An app has no data scope until the host says who it is — which is
+why opening the app's own origin directly renders a refusal panel rather than
+the app.
+
+## Entry points
+
+| Import | What it is |
+|---|---|
+| `@frontera-sdk/core/create-frontera-app` | app bootstrap and `useFronteraApp` |
+| `@frontera-sdk/core/client` | the typed platform client |
+| `@frontera-sdk/core/config` | credential and origin resolution |
+| `@frontera-sdk/core/bridge-client` | the host handshake, if you need it directly |
+| `@frontera-sdk/core/bridge-protocol` | the message types both sides speak |
+| `@frontera-sdk/core/app-state` | shared, validated app state |
+| `@frontera-sdk/core/theme` | applying the host's design tokens |
+| `@frontera-sdk/core/errors` | the error taxonomy, `code` mirroring the service |
+
+Published as TypeScript source. Every consumer is a bundler or `tsc`, so a
+build step would emit output the consumer immediately re-transpiles.
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@frontera-sdk/core",
+  "version": "0.1.0",
+  "description": "Frontera app runtime: the platform bridge client, app bootstrap and typed platform client.",
+  "keywords": [
+    "frontera",
+    "sdk",
+    "iframe",
+    "bridge"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "src",
+    "!src/__tests__",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./errors": {
+      "types": "./src/errors.ts",
+      "import": "./src/errors.ts"
+    },
+    "./config": {
+      "types": "./src/config.ts",
+      "import": "./src/config.ts"
+    },
+    "./transport": {
+      "types": "./src/transport.ts",
+      "import": "./src/transport.ts"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "import": "./src/client.ts"
+    },
+    "./theme": {
+      "types": "./src/theme.ts",
+      "import": "./src/theme.ts"
+    },
+    "./bridge-client": {
+      "types": "./src/bridge-client.ts",
+      "import": "./src/bridge-client.ts"
+    },
+    "./bridge-protocol": {
+      "types": "./src/bridge-protocol.ts",
+      "import": "./src/bridge-protocol.ts"
+    },
+    "./app-state": {
+      "types": "./src/app-state.ts",
+      "import": "./src/app-state.ts"
+    },
+    "./create-frontera-app": {
+      "types": "./src/create-frontera-app.tsx",
+      "import": "./src/create-frontera-app.tsx"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.90.21",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.11.1",
+    "@tanstack/react-query": "^5.90.21",
+    "@types/bun": "latest",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/app-state.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared app state: typed, validated, and legible to a mounted agent.
+ *
+ * Free-form JSON was explicitly rejected. It types as `any`, so a typo compiles,
+ * and a write from a stale app version or a guessing agent can put a string
+ * where the app expects an object and take the render down — worse than V1,
+ * where a schema made invalid state unrepresentable.
+ *
+ * One declaration does three jobs: it types `useAppState` via inference, it
+ * validates every read and write at runtime, and the build emits it as JSON
+ * Schema so the agent receives a typed tool rather than a free-form object.
+ */
+
+/** Minimal structural type for a Zod-like schema, so this file has no Zod dependency. */
+export interface StandardSchema<T> {
+  safeParse(value: unknown): { success: true; data: T } | { success: false; error: unknown }
+}
+
+export interface AppStateDefinition<T extends Record<string, unknown>> {
+  schema: StandardSchema<T>
+  defaults: T
+  /** Per-key schemas, when available, enable per-key recovery. */
+  shape?: Record<string, StandardSchema<unknown>>
+}
+
+export interface DefineAppStateInput<T extends Record<string, unknown>> {
+  schema: StandardSchema<T> & { shape?: Record<string, StandardSchema<unknown>> }
+  defaults: T
+}
+
+export function defineAppState<T extends Record<string, unknown>>(
+  input: DefineAppStateInput<T>,
+): AppStateDefinition<T> {
+  return {
+    schema: input.schema,
+    defaults: input.defaults,
+    shape: (input.schema as { shape?: Record<string, StandardSchema<unknown>> }).shape,
+  }
+}
+
+export interface RecoveryResult<T> {
+  state: T
+  /** Keys that failed validation and were reset to their default. */
+  repaired: string[]
+  /** Keys present in storage but absent from the schema — hidden, not dropped. */
+  unknown: string[]
+}
+
+/**
+ * Parse a stored state document into something the app can render.
+ *
+ * **Invariant: this never throws.** Recovery is per key — a malformed or
+ * missing key resets to its default while valid keys survive — so the app
+ * always receives a well-formed, correctly-typed object. Unknown keys (written
+ * by a newer version, or invented by an agent) are hidden from the app but
+ * PRESERVED by the caller in storage, so a rollback does not lose them.
+ *
+ * Whole-document validation is tried first because it is the common path and
+ * cheap; per-key recovery is the fallback that keeps a single bad field from
+ * blanking everything else.
+ */
+export function parseAppState<T extends Record<string, unknown>>(
+  definition: AppStateDefinition<T>,
+  stored: unknown,
+): RecoveryResult<T> {
+  const document = (typeof stored === 'object' && stored !== null ? stored : {}) as Record<string, unknown>
+
+  const whole = definition.schema.safeParse(document)
+  if (whole.success) {
+    // Project onto known keys explicitly rather than trusting the schema to
+    // strip: a `.passthrough()` (or any hand-rolled) schema would otherwise
+    // hand the app a key it has no type for.
+    const projected = {} as Record<string, unknown>
+    for (const key of Object.keys(definition.defaults)) {
+      projected[key] = (whole.data as Record<string, unknown>)[key] ?? definition.defaults[key]
+    }
+    return {
+      state: projected as T,
+      repaired: [],
+      unknown: Object.keys(document).filter((k) => !(k in definition.defaults)),
+    }
+  }
+
+  const state = { ...definition.defaults } as Record<string, unknown>
+  const repaired: string[] = []
+  const unknownKeys: string[] = []
+
+  for (const key of Object.keys(document)) {
+    if (!(key in definition.defaults)) {
+      unknownKeys.push(key)
+      continue
+    }
+    const keySchema = definition.shape?.[key]
+    if (!keySchema) {
+      // No per-key schema available: accept only if it matches the default's
+      // primitive shape, otherwise fall back. Cheap, and better than trusting it.
+      const sameShape = typeof document[key] === typeof definition.defaults[key]
+      if (sameShape) state[key] = document[key]
+      else repaired.push(key)
+      continue
+    }
+    const parsed = keySchema.safeParse(document[key])
+    if (parsed.success) state[key] = parsed.data
+    else repaired.push(key)
+  }
+
+  // Keys the document omitted entirely already hold their default.
+  return { state: state as T, repaired, unknown: unknownKeys }
+}

package/src/bridge-client.ts

@@ -0,0 +1,152 @@
+import { isHostMessage, type BridgeInit, type AppMessage } from './bridge-protocol'
+import { readRuntimeGlobal } from './config'
+import type { HostTheme } from './theme'
+
+/**
+ * App side of the bridge.
+ *
+ * The app announces itself with `frontera:ready` and waits for `frontera:init`,
+ * which carries the API credential. It does NOT read the credential from its
+ * own URL — the only thing there is the narrow asset token, and treating that
+ * as a data credential would turn a loggable URL into data access.
+ *
+ * `event.origin` is checked against the parent's origin on every message.
+ */
+export interface BridgeSession {
+  init: BridgeInit
+  /** Send a message to the host. */
+  send(message: AppMessage): void
+  /** Subscribe to shared-state updates pushed by the host. */
+  onState(handler: (state: Record<string, unknown>) => void): () => void
+  /** Subscribe to credential refreshes. */
+  onToken(handler: (token: string) => void): () => void
+  /** Subscribe to host palette / colour-scheme changes. */
+  onTheme(handler: (theme: HostTheme) => void): () => void
+  dispose(): void
+}
+
+export interface ConnectOptions {
+  /**
+   * Origin of the embedding platform. Defaults to the injected runtime config,
+   * then `document.referrer`.
+   */
+  parentOrigin?: string
+  timeoutMs?: number
+}
+
+/**
+ * Who is framing us.
+ *
+ * The injected runtime config comes FIRST and `document.referrer` is only a
+ * fallback, which is the opposite of the original order and the reason the
+ * handshake could not complete in production: app responses are served with
+ * `referrer-policy: no-referrer`, so the referrer is empty exactly where it
+ * mattered. `platformOrigin` exists in the injected config for this purpose.
+ */
+function resolveParentOrigin(explicit?: string): string | null {
+  if (explicit) return explicit
+  const injected = readRuntimeGlobal().platformOrigin
+  if (injected) return injected
+  if (typeof document === 'undefined') return null
+  try {
+    return document.referrer ? new URL(document.referrer).origin : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Complete the handshake.
+ *
+ * Rejects rather than hanging if the host never answers: a frame that waits
+ * forever looks identical to a slow network, and an author debugging a broken
+ * mount deserves a real error.
+ */
+export function connectToHost(options: ConnectOptions = {}): Promise<BridgeSession> {
+  const parentOrigin = resolveParentOrigin(options.parentOrigin)
+  const timeoutMs = options.timeoutMs ?? 10_000
+
+  if (typeof window === 'undefined' || window.parent === window) {
+    return Promise.reject(
+      new Error('Not running inside a Frontera host frame — connectToHost() needs a parent window.'),
+    )
+  }
+  if (!parentOrigin) {
+    return Promise.reject(
+      new Error('Could not determine the host origin; pass parentOrigin explicitly.'),
+    )
+  }
+
+  const stateHandlers = new Set<(s: Record<string, unknown>) => void>()
+  const tokenHandlers = new Set<(t: string) => void>()
+  const themeHandlers = new Set<(t: HostTheme) => void>()
+
+  return new Promise<BridgeSession>((resolve, reject) => {
+    let settled = false
+
+    const send = (message: AppMessage) => window.parent.postMessage(message, parentOrigin)
+
+    const onMessage = (event: MessageEvent) => {
+      if (event.origin !== parentOrigin) return
+      if (!isHostMessage(event.data)) return
+      const message = event.data
+
+      switch (message.type) {
+        case 'frontera:init':
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          resolve({
+            init: message,
+            send,
+            onState(handler) {
+              stateHandlers.add(handler)
+              return () => stateHandlers.delete(handler)
+            },
+            onToken(handler) {
+              tokenHandlers.add(handler)
+              return () => tokenHandlers.delete(handler)
+            },
+            onTheme(handler) {
+              themeHandlers.add(handler)
+              return () => themeHandlers.delete(handler)
+            },
+            dispose() {
+              window.removeEventListener('message', onMessage)
+              stateHandlers.clear()
+              tokenHandlers.clear()
+              themeHandlers.clear()
+            },
+          })
+          break
+        case 'frontera:state':
+          for (const handler of stateHandlers) handler(message.state)
+          break
+        case 'frontera:token':
+          for (const handler of tokenHandlers) handler(message.token)
+          break
+        // The host pushes this on every platform theme change — a system
+        // dark-mode switch, a surface that forces its own scheme. Without a
+        // handler the message was received and dropped, so an app followed the
+        // palette it was mounted with and then never again.
+        case 'frontera:theme':
+          for (const handler of themeHandlers) {
+            handler({ tokens: message.tokens, colorScheme: message.colorScheme })
+          }
+          break
+        default:
+          break
+      }
+    }
+
+    const timer = setTimeout(() => {
+      if (settled) return
+      settled = true
+      window.removeEventListener('message', onMessage)
+      reject(new Error(`Frontera host did not respond within ${timeoutMs}ms`))
+    }, timeoutMs)
+
+    window.addEventListener('message', onMessage)
+    send({ type: 'frontera:ready' })
+  })
+}

package/src/bridge-protocol.ts

@@ -0,0 +1,95 @@
+/**
+ * postMessage protocol between the platform host and an app iframe.
+ *
+ * The app runs on its own origin (`<appId>.apps.<domain>`), so postMessage is
+ * the ONLY channel. Both sides validate `event.origin` on every message: Luigi,
+ * a mature framework with this same architecture, carries an open issue for
+ * omitting exactly that check, and the consequence is any page being able to
+ * drive an embedded app.
+ */
+
+export interface BridgeInit {
+  type: 'frontera:init'
+  /** Scoped API credential. Arrives here, never in a URL. */
+  token: string
+  apiBaseUrl: string
+  appId: string
+  version: string
+  orgId: string | null
+  workspaceId: string | null
+  /**
+   * The host's palette and light/dark state.
+   *
+   * Defaults, not a house style: `applyHostTheme` writes them behind the app's
+   * own stylesheets so a customer's brand still wins.
+   */
+  theme: { tokens: Record<string, string>; colorScheme?: 'light' | 'dark'; fontCss?: string }
+  /** Current shared app state, already validated by the host. */
+  state: Record<string, unknown>
+  /**
+   * Where the app should open, taken from the platform URL.
+   *
+   * The counterpart to `frontera:navigate`: without it a shared link to
+   * `/apps/<slug>/shipments` mounts the app at its home page, and the address
+   * bar describes a view the user is not looking at. Absent means the app's
+   * own default.
+   */
+  path?: string
+}
+
+export type HostMessage =
+  | BridgeInit
+  | { type: 'frontera:state'; state: Record<string, unknown> }
+  | {
+      type: 'frontera:theme'
+      tokens: Record<string, string>
+      colorScheme?: 'light' | 'dark'
+      fontCss?: string
+    }
+  | { type: 'frontera:token'; token: string }
+
+export type AppMessage =
+  | { type: 'frontera:ready' }
+  | { type: 'frontera:navigate'; path: string }
+  | { type: 'frontera:resize'; height: number }
+  | { type: 'frontera:state-write'; patch: Record<string, unknown> }
+  | { type: 'frontera:error'; message: string; stack?: string }
+  | { type: 'frontera:state-repair'; keys: string[] }
+
+export function isHostMessage(data: unknown): data is HostMessage {
+  if (!data || typeof data !== 'object') return false
+  const m = data as Record<string, unknown>
+  switch (m.type) {
+    case 'frontera:init':
+      return typeof m.token === 'string' && typeof m.apiBaseUrl === 'string' && typeof m.appId === 'string'
+    case 'frontera:state':
+      return typeof m.state === 'object' && m.state !== null
+    case 'frontera:theme':
+      return typeof m.tokens === 'object' && m.tokens !== null
+    case 'frontera:token':
+      return typeof m.token === 'string'
+    default:
+      return false
+  }
+}
+
+export function isAppMessage(data: unknown): data is AppMessage {
+  if (!data || typeof data !== 'object') return false
+  const m = data as Record<string, unknown>
+  switch (m.type) {
+    case 'frontera:ready':
+      return true
+    case 'frontera:navigate':
+      return typeof m.path === 'string'
+    case 'frontera:resize':
+      return typeof m.height === 'number' && Number.isFinite(m.height)
+    case 'frontera:state-write':
+      return typeof m.patch === 'object' && m.patch !== null
+    case 'frontera:error':
+      return typeof m.message === 'string'
+    case 'frontera:state-repair':
+      return Array.isArray(m.keys)
+    default:
+      return false
+  }
+}

package/src/client.ts

@@ -0,0 +1,29 @@
+import { resolveConfig, type FronteraConfig, type FronteraCredential } from './config'
+import { httpRequest, type RequestOptions } from './transport'
+
+/**
+ * The transport-level entry point. Domain clients (`@frontera-sdk/blueprint`, and
+ * later chat and automation) take one of these rather than reimplementing
+ * auth, URL building, or error mapping.
+ *
+ * `withCredential` exists because a bridge-hosted app receives a refreshed
+ * token mid-session: swapping produces a new client rather than mutating one
+ * that in-flight requests may still hold.
+ */
+export class FronteraClient {
+  readonly config: FronteraConfig
+  private readonly fetchImpl: typeof fetch
+
+  constructor(config: Partial<FronteraConfig>, fetchImpl: typeof fetch = fetch) {
+    this.config = resolveConfig(config)
+    this.fetchImpl = fetchImpl
+  }
+
+  request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    return httpRequest<T>(this.config, path, options, this.fetchImpl)
+  }
+
+  withCredential(credential: FronteraCredential): FronteraClient {
+    return new FronteraClient({ ...this.config, credential }, this.fetchImpl)
+  }
+}

package/src/config.ts

@@ -0,0 +1,86 @@
+import { FronteraError } from './errors'
+
+/**
+ * How a caller proves who it is.
+ *
+ * `apiKey` is a long-lived `sk-ws-` workspace key, used by servers and CLIs.
+ * `token` is a short-lived credential minted by the platform and handed to an
+ * app at bridge handshake. Both travel as `Authorization: Bearer`; they are
+ * distinct variants because refresh behaviour differs and callers branch on it.
+ */
+export type FronteraCredential =
+  | { kind: 'apiKey'; key: string }
+  | { kind: 'token'; token: string }
+
+export interface FronteraConfig {
+  /** Origin of the Frontera API, without a trailing slash. */
+  apiBaseUrl: string
+  orgId?: string
+  workspaceId?: string
+  credential: FronteraCredential
+}
+
+/**
+ * Shape the app runtime injects into the page at serve time.
+ *
+ * This mirrors `RuntimeConfig` on the serving side, in full. It was previously
+ * narrowed to the three fields `resolveConfig` reads, which made the other two
+ * invisible to every caller — and `platformOrigin` is the one an app cannot do
+ * without: responses carry `referrer-policy: no-referrer`, so `document.referrer`
+ * is empty and this is the ONLY way to learn who is framing you.
+ */
+export interface FronteraRuntimeGlobal {
+  apiBaseUrl?: string
+  orgId?: string
+  workspaceId?: string
+  appId?: string
+  version?: string
+  platformOrigin?: string
+}
+
+export function readRuntimeGlobal(): FronteraRuntimeGlobal {
+  const injected = (globalThis as { __FRONTERA_CONFIG__?: FronteraRuntimeGlobal })
+    .__FRONTERA_CONFIG__
+  return injected ?? {}
+}
+
+function readGlobal(): FronteraRuntimeGlobal {
+  return readRuntimeGlobal()
+}
+
+function missing(field: string): never {
+  throw new FronteraError(
+    `Frontera SDK is not configured: ${field} is missing. Pass it explicitly, or set the matching FRONTERA_* environment variable.`,
+    { code: 'CONFIG_MISSING' },
+  )
+}
+
+/**
+ * Resolve configuration from, in order of precedence: explicit argument, the
+ * runtime global injected into an app page, then environment variables.
+ *
+ * `env` is a parameter rather than a direct `process.env` read so tests never
+ * mutate global state, and so this works unchanged in a browser bundle where
+ * `process` does not exist.
+ */
+export function resolveConfig(
+  explicit?: Partial<FronteraConfig>,
+  env: Record<string, string | undefined> = typeof process === 'undefined' ? {} : process.env,
+): FronteraConfig {
+  const injected = readGlobal()
+
+  const rawBaseUrl = explicit?.apiBaseUrl ?? injected.apiBaseUrl ?? env.FRONTERA_API_URL
+  if (!rawBaseUrl) missing('apiBaseUrl')
+
+  const credential: FronteraCredential | undefined =
+    explicit?.credential ??
+    (env.FRONTERA_TOKEN ? { kind: 'apiKey', key: env.FRONTERA_TOKEN } : undefined)
+  if (!credential) missing('credential')
+
+  return {
+    apiBaseUrl: rawBaseUrl.replace(/\/+$/, ''),
+    orgId: explicit?.orgId ?? injected.orgId ?? env.FRONTERA_ORG_ID,
+    workspaceId: explicit?.workspaceId ?? injected.workspaceId ?? env.FRONTERA_WORKSPACE_ID,
+    credential,
+  }
+}

package/src/create-frontera-app.tsx

@@ -0,0 +1,220 @@
+import {
+  Component,
+  StrictMode,
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ErrorInfo,
+  type ReactNode,
+} from 'react'
+import { createRoot } from 'react-dom/client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+import { connectToHost, type BridgeSession } from './bridge-client'
+import type { BridgeInit } from './bridge-protocol'
+import { FronteraClient } from './client'
+import { applyHostTheme } from './theme'
+
+/**
+ * The entry point every app shares.
+ *
+ * Before this existed, the quickstart asked each author to hand-write the same
+ * thirty-five lines: find the parent origin, postMessage `frontera:ready`,
+ * listen for `frontera:init`, build a client from the token that arrives, and
+ * only then mount. Copied boilerplate is where the origin check gets dropped —
+ * and a missing origin check is the whole vulnerability class this architecture
+ * exists to close. So it is written once, here.
+ *
+ * Mounting is DEFERRED until the handshake completes. An app has no data scope
+ * until the host tells it who it is, so rendering earlier only produces a flash
+ * of unauthorized requests, and every hook would need a "not ready yet" branch.
+ */
+
+export interface FronteraAppValue {
+  /** Everything the host said at handshake, including `path`. */
+  init: BridgeInit
+  client: FronteraClient
+  /** Ask the platform to change its URL — the counterpart to `init.path`. */
+  navigate(path: string): void
+}
+
+const FronteraAppReactContext = createContext<FronteraAppValue | null>(null)
+
+export function useFronteraApp(): FronteraAppValue {
+  const value = useContext(FronteraAppReactContext)
+  if (!value) {
+    throw new Error(
+      'useFronteraApp() outside a Frontera app — createFronteraApp() installs this provider.',
+    )
+  }
+  return value
+}
+
+/**
+ * A wrapper contributed by a domain package.
+ *
+ * This is a callback rather than `createFronteraApp` importing the domain
+ * clients directly, because `@frontera-sdk/blueprint` already depends on
+ * `@frontera-sdk/core` — reaching back the other way would make the two
+ * packages mutually dependent. `blueprintProvider` from
+ * `@frontera-sdk/blueprint/provider` is one of these.
+ */
+export type FronteraProvider = (value: FronteraAppValue, children: ReactNode) => ReactNode
+
+export interface CreateFronteraAppOptions {
+  /** Element id to mount into. Defaults to `root`. */
+  rootId?: string
+  providers?: FronteraProvider[]
+  queryClient?: QueryClient
+  /** How long to wait for the host before reporting a failed mount. */
+  timeoutMs?: number
+}
+
+interface BoundaryProps {
+  onError: (error: Error, info: ErrorInfo) => void
+  children: ReactNode
+}
+
+/**
+ * Report a render crash to the host instead of leaving a blank frame.
+ *
+ * The platform listens for `frontera:error` and surfaces it next to the app, so
+ * the author sees the message rather than an empty rectangle they have to open
+ * devtools to explain.
+ */
+class AppErrorBoundary extends Component<BoundaryProps, { error: Error | null }> {
+  state: { error: Error | null } = { error: null }
+
+  static getDerivedStateFromError(error: Error) {
+    return { error }
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo) {
+    this.props.onError(error, info)
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children
+    return diagnostic('This app stopped rendering', this.state.error.message)
+  }
+}
+
+function diagnostic(title: string, detail: string): ReactNode {
+  return (
+    <div
+      role="alert"
+      style={{
+        fontFamily: 'var(--font-sans, system-ui, sans-serif)',
+        color: 'var(--foreground, #111)',
+        padding: 24,
+        lineHeight: 1.5,
+      }}
+    >
+      <strong>{title}</strong>
+      <div style={{ marginTop: 4, opacity: 0.75, fontSize: 14 }}>{detail}</div>
+    </div>
+  )
+}
+
+/**
+ * Holds what the host can change underneath a running app.
+ *
+ * The credential is state rather than a captured constant because the host
+ * rotates it mid-session; `withCredential` returns a NEW client so requests
+ * already in flight keep the one they started with.
+ */
+function FronteraRoot({
+  session,
+  app,
+  providers,
+}: {
+  session: BridgeSession
+  app: ReactNode
+  providers: FronteraProvider[]
+}) {
+  const { init } = session
+  const [client, setClient] = useState(
+    () =>
+      new FronteraClient({
+        apiBaseUrl: init.apiBaseUrl,
+        orgId: init.orgId ?? undefined,
+        workspaceId: init.workspaceId ?? undefined,
+        credential: { kind: 'apiKey', key: init.token },
+      }),
+  )
+
+  useEffect(
+    () => session.onToken((token) => setClient((c) => c.withCredential({ kind: 'apiKey', key: token }))),
+    [session],
+  )
+
+  useEffect(() => session.onTheme((theme) => applyHostTheme(theme)), [session])
+
+  const value: FronteraAppValue = {
+    init,
+    client,
+    navigate: (path) => session.send({ type: 'frontera:navigate', path }),
+  }
+
+  let tree: ReactNode = app
+  // Applied in reverse so the FIRST provider listed ends up outermost, which is
+  // the order a reader expects from the array.
+  for (const provider of [...providers].reverse()) tree = provider(value, tree)
+
+  return (
+    <FronteraAppReactContext.Provider value={value}>
+      <AppErrorBoundary
+        onError={(error) =>
+          session.send({ type: 'frontera:error', message: error.message, stack: error.stack })
+        }
+      >
+        {tree}
+      </AppErrorBoundary>
+    </FronteraAppReactContext.Provider>
+  )
+}
+
+export async function createFronteraApp(
+  app: ReactNode,
+  options: CreateFronteraAppOptions = {},
+): Promise<void> {
+  const rootId = options.rootId ?? 'root'
+  const element = document.getElementById(rootId)
+  if (!element) {
+    throw new Error(`createFronteraApp: no #${rootId} element — check index.html.`)
+  }
+
+  const root = createRoot(element)
+
+  let session: BridgeSession
+  try {
+    session = await connectToHost({ timeoutMs: options.timeoutMs })
+  } catch (err) {
+    // NOT a thrown rejection. This is the everyday outcome of running `vite`
+    // directly, and an unhandled rejection in the console reads as a crash in
+    // the app's own code. A visible panel says what actually happened.
+    const detail = err instanceof Error ? err.message : String(err)
+    root.render(diagnostic('This app runs inside Frontera', detail))
+    return
+  }
+
+  // Before the first paint, so the app never renders in the wrong palette.
+  applyHostTheme(session.init.theme)
+
+  const queryClient =
+    options.queryClient ??
+    new QueryClient({
+      // Platform data is read-only here and a mounted app is usually one
+      // screen; refetching on every focus change is noise, not freshness.
+      defaultOptions: { queries: { refetchOnWindowFocus: false, retry: 1 } },
+    })
+
+  root.render(
+    <StrictMode>
+      <QueryClientProvider client={queryClient}>
+        <FronteraRoot session={session} app={app} providers={options.providers ?? []} />
+      </QueryClientProvider>
+    </StrictMode>,
+  )
+}

package/src/errors.ts

@@ -0,0 +1,52 @@
+/**
+ * Error taxonomy for the Frontera SDK.
+ *
+ * `code` mirrors the service's `ErrorCode` enum
+ * (packages/service/src/lib/errors.ts) so callers branch on the same strings
+ * the API emits. Codes are deliberately not enumerated here — the service adds
+ * new ones, and an SDK that rejected unknown codes would need a release every
+ * time it did.
+ */
+export class FronteraError extends Error {
+  readonly code: string
+  readonly status?: number
+  readonly details?: unknown
+
+  constructor(message: string, opts: { code: string; status?: number; details?: unknown }) {
+    super(message)
+    this.name = 'FronteraError'
+    this.code = opts.code
+    this.status = opts.status
+    this.details = opts.details
+  }
+}
+
+/** Codes used when the response body carries no envelope of its own. */
+const STATUS_FALLBACK: Record<number, string> = {
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  409: 'CONFLICT',
+  429: 'RATE_LIMITED',
+}
+
+function isErrorEnvelope(body: unknown): body is { error: true; code?: string; message?: string } {
+  return typeof body === 'object' && body !== null && (body as { error?: unknown }).error === true
+}
+
+/** Turn a non-2xx response body into a `FronteraError`. */
+export function errorFromResponse(status: number, body: unknown): FronteraError {
+  if (isErrorEnvelope(body)) {
+    return new FronteraError(body.message ?? `request failed with ${status}`, {
+      code: body.code ?? STATUS_FALLBACK[status] ?? 'INTERNAL_ERROR',
+      status,
+      details: body,
+    })
+  }
+  return new FronteraError(`request failed with ${status}`, {
+    code: STATUS_FALLBACK[status] ?? 'INTERNAL_ERROR',
+    status,
+    details: body ?? undefined,
+  })
+}

package/src/theme.ts

@@ -0,0 +1,69 @@
+/**
+ * Applying the host's palette inside an app.
+ *
+ * The point is that an app sitting in the platform should not look pasted in —
+ * it follows the deployment's colours and its light/dark state without the
+ * author wiring anything.
+ *
+ * The hard part is precedence. An app that has defined its own brand must keep
+ * it; the host is supplying DEFAULTS, not a house style. So host tokens are
+ * written into a stylesheet inserted as the FIRST child of `<head>`, before the
+ * app's own imports. Same `:root` specificity, earlier in the cascade — the
+ * app's `brand.css` still wins every token it names, and inherits the rest.
+ *
+ * Inline styles on the root element would have been simpler and wrong: they
+ * beat every stylesheet, so the host would silently overwrite the customer's
+ * brand the moment it was mounted.
+ */
+
+const STYLE_ID = 'frontera-host-theme'
+
+export interface HostTheme {
+  tokens: Record<string, string>
+  colorScheme?: 'light' | 'dark'
+}
+
+/** CSS custom properties only — never arbitrary declarations from the host. */
+function isTokenName(name: string): boolean {
+  return /^--[a-zA-Z0-9_-]+$/.test(name)
+}
+
+/**
+ * A token value the host sent.
+ *
+ * Restricted because this string is interpolated into a stylesheet: `}` would
+ * close the rule and let anything after it become a new one. The host is
+ * trusted, but a value that escapes its rule is a bug class worth closing at
+ * the boundary rather than reasoning about.
+ */
+function isTokenValue(value: string): boolean {
+  return typeof value === 'string' && value.length < 200 && !/[{}<>;]/.test(value)
+}
+
+export function applyHostTheme(theme: HostTheme | undefined): void {
+  if (typeof document === 'undefined' || !theme) return
+
+  const declarations = Object.entries(theme.tokens ?? {})
+    .filter(([name, value]) => isTokenName(name) && isTokenValue(value))
+    .map(([name, value]) => `${name}: ${value};`)
+    .join('\n  ')
+
+  if (declarations) {
+    let style = document.getElementById(STYLE_ID) as HTMLStyleElement | null
+    if (!style) {
+      style = document.createElement('style')
+      style.id = STYLE_ID
+      // First in <head>, so every app stylesheet that follows can override.
+      document.head.prepend(style)
+    }
+    style.textContent = `:root {\n  ${declarations}\n}`
+  }
+
+  if (theme.colorScheme) {
+    const dark = theme.colorScheme === 'dark'
+    document.documentElement.classList.toggle('dark', dark)
+    // Tells the browser to pick the matching form controls and scrollbars,
+    // which no amount of custom properties can do.
+    document.documentElement.style.colorScheme = dark ? 'dark' : 'light'
+  }
+}

package/src/transport.ts

@@ -0,0 +1,96 @@
+import type { FronteraConfig } from './config'
+import { errorFromResponse } from './errors'
+
+export interface RequestOptions {
+  // PATCH is included because the platform uses it for partial writes —
+  // staging an agent draft is one. The transport already passes any method
+  // straight to fetch, so its absence here was a type narrower than the
+  // runtime, which type-checks a correct call as an error.
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  body?: unknown
+  query?: Record<string, string | number | boolean | undefined>
+  signal?: AbortSignal
+}
+
+/**
+ * Auth and scope headers for one request.
+ *
+ * Both credential kinds travel as `Authorization: Bearer`. `x-org-id` and
+ * `x-workspace-id` mirror what the web app sends and are what the service's
+ * auth middleware reads to scope a session request. A workspace key ignores
+ * them and resolves its own scope from the key row, so they can never widen
+ * access beyond what the credential already allows.
+ */
+export function authHeaders(config: FronteraConfig): Record<string, string> {
+  const token =
+    config.credential.kind === 'apiKey' ? config.credential.key : config.credential.token
+  const headers: Record<string, string> = { authorization: `Bearer ${token}` }
+  if (config.orgId) headers['x-org-id'] = config.orgId
+  if (config.workspaceId) headers['x-workspace-id'] = config.workspaceId
+  return headers
+}
+
+/**
+ * Unwrap the service response envelope when present.
+ *
+ * `ok()` returns `{ data, message, error: false }`, but several routers — the
+ * Blueprint query router among them — return their payload raw. Detect the
+ * envelope rather than assuming it.
+ */
+export function unwrap<T>(body: unknown): T {
+  if (
+    typeof body === 'object' &&
+    body !== null &&
+    !Array.isArray(body) &&
+    (body as { error?: unknown }).error === false &&
+    'data' in body
+  ) {
+    return (body as { data: T }).data
+  }
+  return body as T
+}
+
+function buildUrl(config: FronteraConfig, path: string, query?: RequestOptions['query']): string {
+  const url = new URL(`${config.apiBaseUrl}${path.startsWith('/') ? path : `/${path}`}`)
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      if (value === undefined) continue
+      url.searchParams.set(key, String(value))
+    }
+  }
+  return url.toString()
+}
+
+/**
+ * `fetchImpl` is injectable so tests never touch the network. Production
+ * callers omit it and get the platform `fetch`.
+ */
+export async function httpRequest<T>(
+  config: FronteraConfig,
+  path: string,
+  options: RequestOptions = {},
+  fetchImpl: typeof fetch = fetch,
+): Promise<T> {
+  const headers: Record<string, string> = { ...authHeaders(config), accept: 'application/json' }
+  if (options.body !== undefined) headers['content-type'] = 'application/json'
+
+  const response = await fetchImpl(buildUrl(config, path, options.query), {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body === undefined ? undefined : JSON.stringify(options.body),
+    signal: options.signal,
+  })
+
+  const text = await response.text()
+  let parsed: unknown = null
+  if (text.length > 0) {
+    try {
+      parsed = JSON.parse(text)
+    } catch {
+      parsed = text
+    }
+  }
+
+  if (!response.ok) throw errorFromResponse(response.status, parsed)
+  return unwrap<T>(parsed)
+}