@voyant-travel/apps 0.4.0 → 0.5.0

package/dist/contracts.d.ts

@@ -253,6 +253,32 @@ export declare const appCredentialRevocationSchema: z.ZodObject<{
     installationId: z.ZodString;
     actorId: z.ZodString;
 }, z.core.$strict>;
+export declare const appSessionTokenIssueSchema: z.ZodObject<{
+    entity: z.ZodOptional<z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strict>>;
+    slot: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const appSessionTokenExchangeSchema: z.ZodPipe<z.ZodObject<{
+    session_token: z.ZodString;
+    client_id: z.ZodString;
+    client_secret: z.ZodOptional<z.ZodString>;
+    viewer_scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    contextual_scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>, z.ZodTransform<{
+    client_secret: string | undefined;
+    session_token: string;
+    client_id: string;
+    viewer_scopes: string[];
+    contextual_scopes?: string[] | undefined;
+}, {
+    session_token: string;
+    client_id: string;
+    viewer_scopes: string[];
+    client_secret?: string | undefined;
+    contextual_scopes?: string[] | undefined;
+}>>;
 export type AppManifest = z.infer<typeof appManifestSchema>;
 export type CreateCustomAppRegistrationInput = z.infer<typeof createCustomAppRegistrationSchema>;
 export type ReleaseManifestUploadInput = z.infer<typeof releaseManifestUploadSchema>;
@@ -261,3 +287,5 @@ export type AppListQuery = z.infer<typeof appListQuerySchema>;
 export type AppWebhookReplayInput = z.infer<typeof appWebhookReplaySchema>;
 export type AppOAuthAuthorizeQuery = z.infer<typeof appOAuthAuthorizeQuerySchema>;
 export type AppOAuthTokenInput = z.infer<typeof appOAuthTokenSchema>;
+export type AppSessionTokenIssueInput = z.infer<typeof appSessionTokenIssueSchema>;
+export type AppSessionTokenExchangeInput = z.infer<typeof appSessionTokenExchangeSchema>;

package/dist/contracts.js

@@ -271,3 +271,28 @@ export const appCredentialRevocationSchema = z
     actorId: z.string().trim().min(1),
 })
     .strict();
+const sessionTokenEntitySchema = z
+    .object({
+    type: z.string().trim().min(1).max(80),
+    id: z.string().trim().min(1).max(200),
+})
+    .strict();
+export const appSessionTokenIssueSchema = z
+    .object({
+    entity: sessionTokenEntitySchema.optional(),
+    slot: z.string().trim().min(1).max(80).optional(),
+})
+    .strict();
+export const appSessionTokenExchangeSchema = z
+    .object({
+    session_token: z.string().trim().min(1),
+    client_id: z.string().trim().min(1),
+    client_secret: z.string().trim().optional(),
+    viewer_scopes: z.array(scopeSchema).default([]),
+    contextual_scopes: z.array(scopeSchema).optional(),
+})
+    .strict()
+    .transform((input) => ({
+    ...input,
+    client_secret: input.client_secret?.trim() || undefined,
+}));

package/dist/extension-resolution.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Installation-backed admin extension resolution (RFC §6, Phase 3).
+ *
+ * Replaces the static self-hosted descriptor list as the source of activated
+ * admin extensions: descriptors come from `app_extension_installations` for
+ * `active` installations only, so pausing, degrading, or uninstalling an app
+ * immediately drops its pages and slots. Slot extensions are filtered by
+ * release-pinned `extensionApi` compatibility, and host-rendered labels (nav
+ * entries, extension titles) plus the resolved app locale + text direction come
+ * from the installed release's declared locales and `app_release_localizations`.
+ *
+ * The returned descriptors are the exact shape the admin host consumes; static
+ * deployment-graph descriptors remain supported alongside these.
+ */
+import { type UiExtensionDescriptor } from "@voyant-travel/admin-extension-sdk";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type AppTextDirection, type HostLabelRow } from "./locale-resolution.js";
+/** A resolved slot/dashboard extension plus the app locale its frame renders in. */
+export interface ResolvedUiSlotExtension {
+    descriptor: UiExtensionDescriptor;
+    installationId: string;
+    appId: string;
+    appLocale: string;
+    direction: AppTextDirection;
+}
+/** A resolved full-page app extension mounted under the app-owned admin route. */
+export interface ResolvedAppPage {
+    /** Stable per-installation key (`<installationId>:<manifest key>`). */
+    key: string;
+    installationId: string;
+    appId: string;
+    /** App-owned admin sub-path declared by the manifest (e.g. `/settings`). */
+    path: string;
+    entryUrl: string;
+    /** Host-rendered page title, locale-resolved with deterministic fallback. */
+    title: string;
+    /** Host-rendered navigation label for the page's nav entry. */
+    navLabel: string;
+    appLocale: string;
+    direction: AppTextDirection;
+}
+export interface ResolvedInstalledExtensions {
+    slots: ResolvedUiSlotExtension[];
+    pages: ResolvedAppPage[];
+}
+export interface ResolveInstalledExtensionsInput {
+    deploymentId: string;
+    /** The staff member's active admin locale. */
+    activeLocale: string;
+    /** The extension API version the host implements (defaults to the SDK's). */
+    extensionApiVersion?: string;
+}
+/** One row of an active installation's active extension, as read from the store. */
+export interface InstalledExtensionRow {
+    installationId: string;
+    appId: string;
+    extensionKey: string;
+    descriptor: Record<string, unknown>;
+    releaseId: string;
+    defaultLocale: string;
+    supportedLocales: readonly string[];
+}
+export declare function resolveInstalledExtensions(db: PostgresJsDatabase, input: ResolveInstalledExtensionsInput): Promise<ResolvedInstalledExtensions>;
+/**
+ * Pure assembly of resolved descriptors from store rows and localization data.
+ * Applies compatibility filtering, locale resolution, and host-label lookup.
+ * The `rows` are assumed to already be scoped to active installations/extensions.
+ */
+export declare function assembleInstalledExtensions(rows: readonly InstalledExtensionRow[], localizationsByRelease: Map<string, HostLabelRow[]>, options: {
+    activeLocale: string;
+    extensionApiVersion?: string;
+}): ResolvedInstalledExtensions;

package/dist/extension-resolution.js

@@ -0,0 +1,159 @@
+/**
+ * Installation-backed admin extension resolution (RFC §6, Phase 3).
+ *
+ * Replaces the static self-hosted descriptor list as the source of activated
+ * admin extensions: descriptors come from `app_extension_installations` for
+ * `active` installations only, so pausing, degrading, or uninstalling an app
+ * immediately drops its pages and slots. Slot extensions are filtered by
+ * release-pinned `extensionApi` compatibility, and host-rendered labels (nav
+ * entries, extension titles) plus the resolved app locale + text direction come
+ * from the installed release's declared locales and `app_release_localizations`.
+ *
+ * The returned descriptors are the exact shape the admin host consumes; static
+ * deployment-graph descriptors remain supported alongside these.
+ */
+import { ADMIN_UI_EXTENSION_API_VERSION, isUiExtensionCompatible, } from "@voyant-travel/admin-extension-sdk";
+import { and, eq, inArray } from "drizzle-orm";
+import { createHostLabelResolver, resolveAppLocale, } from "./locale-resolution.js";
+import { appExtensionInstallations, appInstallations, appReleaseLocalizations, appReleases, } from "./schema.js";
+export async function resolveInstalledExtensions(db, input) {
+    const rows = await db
+        .select({
+        installationId: appInstallations.id,
+        appId: appInstallations.appId,
+        extensionKey: appExtensionInstallations.extensionKey,
+        descriptor: appExtensionInstallations.descriptor,
+        releaseId: appExtensionInstallations.releaseId,
+        defaultLocale: appReleases.defaultLocale,
+        supportedLocales: appReleases.supportedLocales,
+    })
+        .from(appExtensionInstallations)
+        .innerJoin(appInstallations, eq(appExtensionInstallations.installationId, appInstallations.id))
+        .innerJoin(appReleases, eq(appExtensionInstallations.releaseId, appReleases.id))
+        .where(and(eq(appInstallations.deploymentId, input.deploymentId), 
+    // Active installations only: paused/degraded/uninstalled apps unmount.
+    eq(appInstallations.status, "active"), eq(appExtensionInstallations.status, "active")));
+    const localizationsByRelease = await loadLocalizations(db, rows.map((row) => row.releaseId));
+    return assembleInstalledExtensions(rows, localizationsByRelease, {
+        activeLocale: input.activeLocale,
+        extensionApiVersion: input.extensionApiVersion,
+    });
+}
+/**
+ * Pure assembly of resolved descriptors from store rows and localization data.
+ * Applies compatibility filtering, locale resolution, and host-label lookup.
+ * The `rows` are assumed to already be scoped to active installations/extensions.
+ */
+export function assembleInstalledExtensions(rows, localizationsByRelease, options) {
+    const version = options.extensionApiVersion ?? ADMIN_UI_EXTENSION_API_VERSION;
+    const slots = [];
+    const pages = [];
+    for (const row of rows) {
+        const declaration = {
+            defaultLocale: row.defaultLocale,
+            supportedLocales: row.supportedLocales,
+        };
+        const locale = resolveAppLocale(options.activeLocale, declaration);
+        const labels = createHostLabelResolver(localizationsByRelease.get(row.releaseId) ?? [], locale.appLocale, declaration.defaultLocale);
+        if (row.extensionKey.startsWith("page:")) {
+            const page = parsePageDescriptor(row.descriptor);
+            if (!page)
+                continue;
+            const title = labels.resolve(page.titleKey, ["extension", "navigation"]) ?? page.key;
+            const navLabel = labels.resolve(page.titleKey, ["navigation", "extension"]) ?? title;
+            pages.push({
+                key: `${row.installationId}:${page.key}`,
+                installationId: row.installationId,
+                appId: row.appId,
+                path: page.path,
+                entryUrl: page.entryUrl,
+                title,
+                navLabel,
+                appLocale: locale.appLocale,
+                direction: locale.direction,
+            });
+            continue;
+        }
+        if (row.extensionKey.startsWith("slot:")) {
+            const slot = parseSlotDescriptor(row.descriptor);
+            if (!slot)
+                continue;
+            // Release-pinned compatibility filter: an incompatible extension is not
+            // mounted (the host's render-time check is defense-in-depth).
+            if (!isUiExtensionCompatible(slot.extensionApi, version))
+                continue;
+            const displayName = labels.resolve(slot.titleKey, ["extension", "navigation"]) ?? slot.key;
+            slots.push({
+                descriptor: {
+                    key: `${row.installationId}:${slot.key}`,
+                    version: slot.version,
+                    displayName,
+                    extensionApi: slot.extensionApi,
+                    entryUrl: slot.entryUrl,
+                    slots: slot.slots,
+                    ...(slot.config ? { config: slot.config } : {}),
+                },
+                installationId: row.installationId,
+                appId: row.appId,
+                appLocale: locale.appLocale,
+                direction: locale.direction,
+            });
+        }
+    }
+    return { slots, pages };
+}
+async function loadLocalizations(db, releaseIds) {
+    const unique = [...new Set(releaseIds)];
+    const grouped = new Map();
+    if (unique.length === 0)
+        return grouped;
+    const rows = await db
+        .select({
+        releaseId: appReleaseLocalizations.releaseId,
+        locale: appReleaseLocalizations.locale,
+        surface: appReleaseLocalizations.surface,
+        messageKey: appReleaseLocalizations.messageKey,
+        text: appReleaseLocalizations.text,
+    })
+        .from(appReleaseLocalizations)
+        .where(inArray(appReleaseLocalizations.releaseId, unique));
+    for (const row of rows) {
+        const list = grouped.get(row.releaseId) ?? [];
+        list.push({
+            locale: row.locale,
+            surface: row.surface,
+            messageKey: row.messageKey,
+            text: row.text,
+        });
+        grouped.set(row.releaseId, list);
+    }
+    return grouped;
+}
+function parsePageDescriptor(value) {
+    const key = stringField(value.key);
+    const titleKey = stringField(value.titleKey);
+    const path = stringField(value.path);
+    const entryUrl = stringField(value.entryUrl);
+    if (!key || !titleKey || !path || !entryUrl)
+        return null;
+    return { key, titleKey, path, entryUrl };
+}
+function parseSlotDescriptor(value) {
+    const key = stringField(value.key);
+    const titleKey = stringField(value.titleKey);
+    const version = stringField(value.version);
+    const extensionApi = stringField(value.extensionApi);
+    const entryUrl = stringField(value.entryUrl);
+    const slots = Array.isArray(value.slots)
+        ? value.slots.filter((slot) => typeof slot === "string")
+        : [];
+    if (!key || !titleKey || !version || !extensionApi || !entryUrl || slots.length === 0)
+        return null;
+    const config = value.config && typeof value.config === "object" && !Array.isArray(value.config)
+        ? value.config
+        : undefined;
+    return { key, titleKey, version, extensionApi, entryUrl, slots, config };
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/extension-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/extension-resolution.test.js

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { assembleInstalledExtensions } from "./extension-resolution.js";
+function slotRow(overrides = {}) {
+    return {
+        installationId: "apin_1",
+        appId: "app_1",
+        extensionKey: "slot:reports",
+        releaseId: "aprl_1",
+        defaultLocale: "en",
+        supportedLocales: ["en", "pt"],
+        descriptor: {
+            key: "reports",
+            titleKey: "reports.title",
+            version: "1.0.0",
+            extensionApi: "^1",
+            entryUrl: "https://app.example.com/reports",
+            slots: ["dashboard.header"],
+        },
+        ...overrides,
+    };
+}
+function pageRow(overrides = {}) {
+    return {
+        installationId: "apin_1",
+        appId: "app_1",
+        extensionKey: "page:settings",
+        releaseId: "aprl_1",
+        defaultLocale: "en",
+        supportedLocales: ["en", "pt"],
+        descriptor: {
+            key: "settings",
+            titleKey: "settings.title",
+            path: "/settings",
+            entryUrl: "https://app.example.com/settings",
+        },
+        ...overrides,
+    };
+}
+const localizations = new Map([
+    [
+        "aprl_1",
+        [
+            { locale: "en", surface: "extension", messageKey: "reports.title", text: "Reports" },
+            { locale: "pt", surface: "extension", messageKey: "reports.title", text: "Relatórios" },
+            { locale: "en", surface: "navigation", messageKey: "settings.title", text: "Settings" },
+            { locale: "en", surface: "extension", messageKey: "settings.title", text: "App Settings" },
+        ],
+    ],
+]);
+describe("assembleInstalledExtensions", () => {
+    it("resolves slot descriptors with host labels and locale/direction", () => {
+        const result = assembleInstalledExtensions([slotRow()], localizations, { activeLocale: "pt" });
+        expect(result.slots).toHaveLength(1);
+        const slot = result.slots[0];
+        expect(slot?.descriptor.key).toBe("apin_1:reports");
+        expect(slot?.descriptor.displayName).toBe("Relatórios");
+        expect(slot?.descriptor.slots).toEqual(["dashboard.header"]);
+        expect(slot?.appLocale).toBe("pt");
+        expect(slot?.direction).toBe("ltr");
+    });
+    it("resolves full-page descriptors with title and nav label", () => {
+        const result = assembleInstalledExtensions([pageRow()], localizations, { activeLocale: "en" });
+        expect(result.pages).toHaveLength(1);
+        const page = result.pages[0];
+        expect(page?.key).toBe("apin_1:settings");
+        expect(page?.path).toBe("/settings");
+        expect(page?.title).toBe("App Settings");
+        expect(page?.navLabel).toBe("Settings");
+    });
+    it("filters out extensionApi-incompatible slot extensions", () => {
+        const incompatible = slotRow({
+            descriptor: {
+                key: "legacy",
+                titleKey: "reports.title",
+                version: "1.0.0",
+                extensionApi: "^0.9",
+                entryUrl: "https://app.example.com/legacy",
+                slots: ["dashboard.header"],
+            },
+        });
+        const result = assembleInstalledExtensions([incompatible], localizations, {
+            activeLocale: "en",
+            extensionApiVersion: "1.1.0",
+        });
+        expect(result.slots).toHaveLength(0);
+    });
+    it("falls back to the descriptor key when no host label exists", () => {
+        const result = assembleInstalledExtensions([slotRow({ releaseId: "aprl_none" })], new Map(), {
+            activeLocale: "en",
+        });
+        expect(result.slots[0]?.descriptor.displayName).toBe("reports");
+    });
+    it("falls back to the default locale for an unsupported active locale", () => {
+        const result = assembleInstalledExtensions([slotRow()], localizations, { activeLocale: "de" });
+        expect(result.slots[0]?.appLocale).toBe("en");
+        expect(result.slots[0]?.descriptor.displayName).toBe("Reports");
+    });
+    it("skips malformed descriptors (fail-soft)", () => {
+        const malformed = slotRow({ descriptor: { key: "broken" } });
+        const result = assembleInstalledExtensions([malformed], localizations, { activeLocale: "en" });
+        expect(result.slots).toHaveLength(0);
+        expect(result.pages).toHaveLength(0);
+    });
+    it("gives each installation a unique descriptor key", () => {
+        const result = assembleInstalledExtensions([slotRow(), slotRow({ installationId: "apin_2" })], localizations, { activeLocale: "en" });
+        expect(result.slots.map((slot) => slot.descriptor.key)).toEqual([
+            "apin_1:reports",
+            "apin_2:reports",
+        ]);
+    });
+});

package/dist/index.d.ts

@@ -5,12 +5,16 @@ export * from "./app-api-service.js";
 export * from "./compiler.js";
 export * from "./consent.js";
 export * from "./contracts.js";
+export * from "./extension-resolution.js";
 export * from "./ingestion.js";
 export * from "./installation-service.js";
+export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";
 export * from "./oauth-service.js";
 export { createAppsAdminRoutes } from "./routes.js";
-export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
+export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, appSessionTokens, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
 export { createAppsService } from "./service.js";
+export * from "./session-token.js";
+export * from "./session-token-service.js";
 export type { AppWebhookDeliveryOptions } from "./webhook-delivery.js";
 export { createAppWebhookDeliveryStore, createAppWebhookEventQueue, enqueueAppWebhookEvent, listAppWebhookHealth, replayAppWebhookDelivery, } from "./webhook-delivery.js";

package/dist/index.js

@@ -5,11 +5,15 @@ export * from "./app-api-service.js";
 export * from "./compiler.js";
 export * from "./consent.js";
 export * from "./contracts.js";
+export * from "./extension-resolution.js";
 export * from "./ingestion.js";
 export * from "./installation-service.js";
+export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";
 export * from "./oauth-service.js";
 export { createAppsAdminRoutes } from "./routes.js";
-export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
+export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, appSessionTokens, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
 export { createAppsService } from "./service.js";
+export * from "./session-token.js";
+export * from "./session-token-service.js";
 export { createAppWebhookDeliveryStore, createAppWebhookEventQueue, enqueueAppWebhookEvent, listAppWebhookHealth, replayAppWebhookDelivery, } from "./webhook-delivery.js";

package/dist/locale-resolution.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic app-locale resolution for the extension host (RFC §6.1).
+ *
+ * The host always passes the staff member's active locale to the frame. It also
+ * resolves an "app locale" against the installed release's declared locales so
+ * host-rendered labels (nav entries, extension titles) and the frame's initial
+ * direction are chosen consistently:
+ *
+ *   1. exact active-locale match;
+ *   2. progressively less specific language match (`pt-BR` → `pt`);
+ *   3. the app's declared default locale.
+ *
+ * Everything here is pure and BCP 47 aware only to the extent of splitting on
+ * the primary subtag — the app remains authoritative for its in-frame
+ * translations and may choose a more sophisticated fallback itself.
+ */
+export type AppTextDirection = "ltr" | "rtl";
+/** Text direction for a locale, from its primary language subtag. */
+export declare function resolveTextDirection(locale: string): AppTextDirection;
+export interface AppLocaleDeclaration {
+    defaultLocale: string;
+    supportedLocales: readonly string[];
+}
+export interface ResolvedAppLocale {
+    /** The active admin locale the host requested resolution for. */
+    requestedLocale: string;
+    /** The declared locale the host resolved to (exact → language → default). */
+    appLocale: string;
+    /** Text direction for {@link appLocale}. */
+    direction: AppTextDirection;
+}
+/**
+ * Resolve the app locale for an active admin locale against a release's
+ * declared locales. The returned `appLocale` is always one of the declared
+ * tags (falling back to `defaultLocale`), preserving the declared casing.
+ */
+export declare function resolveAppLocale(activeLocale: string, declaration: AppLocaleDeclaration): ResolvedAppLocale;
+/** One flattened host-rendered localization row (matches `app_release_localizations`). */
+export interface HostLabelRow {
+    locale: string;
+    surface: string;
+    messageKey: string;
+    text: string;
+}
+export interface HostLabelResolver {
+    /**
+     * Resolve a host-rendered label for a message key, trying the resolved app
+     * locale first and then the default locale (host labels use the platform
+     * algorithm, never the app's in-frame fallback). Returns null when no
+     * declared surface carries the key.
+     */
+    resolve(messageKey: string, surfaces?: readonly string[]): string | null;
+}
+/**
+ * Build a resolver over a release's localization rows for a resolved app locale
+ * with default-locale fallback. Missing translations fall back deterministically
+ * rather than throwing, so an incomplete non-default locale never blocks mount.
+ */
+export declare function createHostLabelResolver(rows: readonly HostLabelRow[], appLocale: string, defaultLocale: string): HostLabelResolver;

package/dist/locale-resolution.js

@@ -0,0 +1,113 @@
+/**
+ * Deterministic app-locale resolution for the extension host (RFC §6.1).
+ *
+ * The host always passes the staff member's active locale to the frame. It also
+ * resolves an "app locale" against the installed release's declared locales so
+ * host-rendered labels (nav entries, extension titles) and the frame's initial
+ * direction are chosen consistently:
+ *
+ *   1. exact active-locale match;
+ *   2. progressively less specific language match (`pt-BR` → `pt`);
+ *   3. the app's declared default locale.
+ *
+ * Everything here is pure and BCP 47 aware only to the extent of splitting on
+ * the primary subtag — the app remains authoritative for its in-frame
+ * translations and may choose a more sophisticated fallback itself.
+ */
+/**
+ * Primary language subtags written right-to-left. Kept small and explicit; the
+ * frame receives the resolved direction so it never has to infer it from an
+ * incomplete language list.
+ */
+const RTL_LANGUAGES = new Set([
+    "ar", // Arabic
+    "arc", // Aramaic
+    "ckb", // Central Kurdish (Sorani)
+    "dv", // Divehi
+    "fa", // Persian
+    "he", // Hebrew
+    "ku", // Kurdish
+    "ps", // Pashto
+    "sd", // Sindhi
+    "syr", // Syriac
+    "ur", // Urdu
+    "yi", // Yiddish
+]);
+/** The primary language subtag of a BCP 47 tag, lowercased. */
+function primaryLanguage(locale) {
+    return locale.trim().toLowerCase().split(/[-_]/)[0] ?? "";
+}
+/** Text direction for a locale, from its primary language subtag. */
+export function resolveTextDirection(locale) {
+    return RTL_LANGUAGES.has(primaryLanguage(locale)) ? "rtl" : "ltr";
+}
+/**
+ * Resolve the app locale for an active admin locale against a release's
+ * declared locales. The returned `appLocale` is always one of the declared
+ * tags (falling back to `defaultLocale`), preserving the declared casing.
+ */
+export function resolveAppLocale(activeLocale, declaration) {
+    const requested = activeLocale.trim();
+    const normalized = requested.toLowerCase();
+    const supported = declaration.supportedLocales;
+    const exact = supported.find((candidate) => candidate.toLowerCase() === normalized);
+    if (exact) {
+        return { requestedLocale: requested, appLocale: exact, direction: resolveTextDirection(exact) };
+    }
+    const requestedLanguage = primaryLanguage(requested);
+    if (requestedLanguage) {
+        const languageMatch = supported.find((candidate) => primaryLanguage(candidate) === requestedLanguage);
+        if (languageMatch) {
+            return {
+                requestedLocale: requested,
+                appLocale: languageMatch,
+                direction: resolveTextDirection(languageMatch),
+            };
+        }
+    }
+    return {
+        requestedLocale: requested,
+        appLocale: declaration.defaultLocale,
+        direction: resolveTextDirection(declaration.defaultLocale),
+    };
+}
+const DEFAULT_LABEL_SURFACES = ["extension", "navigation", "setup", "app"];
+/**
+ * Build a resolver over a release's localization rows for a resolved app locale
+ * with default-locale fallback. Missing translations fall back deterministically
+ * rather than throwing, so an incomplete non-default locale never blocks mount.
+ */
+export function createHostLabelResolver(rows, appLocale, defaultLocale) {
+    // locale → surface → messageKey → text
+    const byLocale = new Map();
+    for (const row of rows) {
+        const locale = row.locale.toLowerCase();
+        let surfaces = byLocale.get(locale);
+        if (!surfaces) {
+            surfaces = new Map();
+            byLocale.set(locale, surfaces);
+        }
+        let keys = surfaces.get(row.surface);
+        if (!keys) {
+            keys = new Map();
+            surfaces.set(row.surface, keys);
+        }
+        keys.set(row.messageKey, row.text);
+    }
+    const localePreference = [appLocale.toLowerCase(), defaultLocale.toLowerCase()];
+    return {
+        resolve(messageKey, surfaces = DEFAULT_LABEL_SURFACES) {
+            for (const locale of localePreference) {
+                const surfaceMap = byLocale.get(locale);
+                if (!surfaceMap)
+                    continue;
+                for (const surface of surfaces) {
+                    const text = surfaceMap.get(surface)?.get(messageKey);
+                    if (text !== undefined)
+                        return text;
+                }
+            }
+            return null;
+        },
+    };
+}

package/dist/locale-resolution.test.d.ts

@@ -0,0 +1 @@
+export {};