@foir/sdk 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -108,6 +108,25 @@ nobody asking for `@foir/sdk` gets it early. The push that carries the commit to
 
 Changes on `dev` that have not been published to npm.
 
+## [0.16.0] — 2026-10-02
+
+Published under npm's `next` tag from `dev`, as 0.15.0 was; `latest` moves to
+it at the next promotion.
+
+### Added
+
+- **An embedded page is told how the console looks** (`@foir/sdk/placement`).
+  The console's theme is the operator's own setting, which a framed page cannot
+  see, so a page that followed the system's preference could sit dark inside a
+  light console. `connectPlacement` takes `onAppearance`, called with
+  `{ theme: 'light' | 'dark' }` as soon as the console says (before the token
+  arrives) and again whenever the operator changes it; `session.appearance`
+  holds the current one. `PlacementAppearance` is the type, and
+  `PLACEMENT_MESSAGE.appearance` the message.
+- A console older than this says nothing: `onAppearance` is not called and
+  `session.appearance` is `null`, so keep the system's preference as the
+  fallback.
+
 ## [0.15.0] — 2026-10-02
 
 Published under npm's `next` tag from `dev`, because it calls parts of the

package/dist/placement/index.d.ts

@@ -19,6 +19,10 @@
  * const data = await session.request('{ preorders { items { id } } }');
  * ```
  *
+ * The console also tells the page how it looks, so the page can match it: pass
+ * `onAppearance` and apply the theme it names. The operator's console theme is
+ * their own setting and need not be their system's.
+ *
  * The browser shows the page blank, however well it is authenticated, unless
  * the page allows the console as a frame ancestor. Hydrogen and many other
  * frameworks send `frame-ancestors 'none'` by default. `placementFrameAncestors`
@@ -37,6 +41,8 @@ export declare const PLACEMENT_MESSAGE: {
     readonly refused: "foir:placement:refused";
     /** Console to page: the operator signed out. */
     readonly signedOut: "foir:placement:signed-out";
+    /** Console to page: how the console looks, now and whenever it changes. */
+    readonly appearance: "foir:placement:appearance";
 };
 /** What the console hands an embedded page. */
 export interface PlacementGrant {
@@ -54,6 +60,14 @@ export interface PlacementGrant {
         reason: string;
     }[];
 }
+/** How the console looks, for an embedded page to match. */
+export interface PlacementAppearance {
+    /**
+     * The console's theme as the operator sees it: their own choice, or their
+     * system's when they left it to the system.
+     */
+    theme: 'light' | 'dark';
+}
 /** A message the console sends an embedded page. */
 export type PlacementHostMessage = {
     type: typeof PLACEMENT_MESSAGE.token;
@@ -63,6 +77,9 @@ export type PlacementHostMessage = {
     reason: string;
 } | {
     type: typeof PLACEMENT_MESSAGE.signedOut;
+} | {
+    type: typeof PLACEMENT_MESSAGE.appearance;
+    appearance: PlacementAppearance;
 };
 /** A message an embedded page sends the console. */
 export type PlacementPageMessage = {
@@ -100,6 +117,13 @@ export interface ConnectPlacementOptions {
     timeoutMs?: number;
     /** How long before expiry to ask for a fresh token. Default 60 seconds. */
     refreshBeforeMs?: number;
+    /**
+     * Called with how the console looks: once as soon as the console says, which
+     * is before the token arrives, and again whenever the operator changes it.
+     * Apply it instead of the system's preference, so the page matches the
+     * console it is shown in.
+     */
+    onAppearance?: (appearance: PlacementAppearance) => void;
     /** The page's window. Default the global one; tests pass their own. */
     window?: Window;
     /** The fetch the session's requests use. Default the global one. */
@@ -109,6 +133,11 @@ export interface ConnectPlacementOptions {
 export interface PlacementSession {
     /** The grant in force now. Replaced as the session refreshes. */
     readonly grant: PlacementGrant;
+    /**
+     * How the console looks now, or null when the console has not said (a console
+     * older than this). Kept current as the operator changes it.
+     */
+    readonly appearance: PlacementAppearance | null;
     /** Whether the token carries this scope, to hide or grey out what the operator cannot do. */
     can(scope: string): boolean;
     /** A GraphQL request to Foir's API as the operator, through your app. */

package/dist/placement.js

@@ -9,7 +9,9 @@ var PLACEMENT_MESSAGE = {
   /** Console to page: no token, and why. */
   refused: "foir:placement:refused",
   /** Console to page: the operator signed out. */
-  signedOut: "foir:placement:signed-out"
+  signedOut: "foir:placement:signed-out",
+  /** Console to page: how the console looks, now and whenever it changes. */
+  appearance: "foir:placement:appearance"
 };
 var FOIR_CONSOLE_ORIGINS = {
   production: ["https://app.foir.io"],
@@ -41,6 +43,10 @@ var PlacementRefused = class extends Error {
 function isHostMessage(data) {
   if (typeof data !== "object" || data === null) return false;
   const t = data.type;
+  if (t === PLACEMENT_MESSAGE.appearance) {
+    const theme = data.appearance?.theme;
+    return theme === "light" || theme === "dark";
+  }
   return t === PLACEMENT_MESSAGE.token || t === PLACEMENT_MESSAGE.refused || t === PLACEMENT_MESSAGE.signedOut;
 }
 function connectPlacement(options) {
@@ -55,6 +61,7 @@ function connectPlacement(options) {
   }
   return new Promise((resolve, reject) => {
     let grant = null;
+    let appearance = null;
     let settled = false;
     let refreshTimer;
     const signedOut = /* @__PURE__ */ new Set();
@@ -77,6 +84,9 @@ function connectPlacement(options) {
         if (!grant) throw new PlacementRefused("the operator has signed out");
         return grant;
       },
+      get appearance() {
+        return appearance;
+      },
       can: (scope) => grant?.grantedScopes.includes(scope) ?? false,
       async request(document, variables) {
         if (!grant) throw new PlacementRefused("the operator has signed out");
@@ -123,6 +133,10 @@ function connectPlacement(options) {
           close();
           for (const l of signedOut) l();
           return;
+        case PLACEMENT_MESSAGE.appearance:
+          appearance = { theme: msg.appearance.theme };
+          options.onAppearance?.(appearance);
+          return;
       }
     }
     const timeout = setTimeout(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foir/sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Official Foir SDK — editor iframe client + server-side platform helpers",
   "type": "module",
   "publishConfig": {