@thekatze/locolize-core 0.0.0-stage → 0.1.0-test.0

package/dist/adapters/custom.d.ts

@@ -0,0 +1,15 @@
+import { Adapter, LocolizeConfig } from "../types.js";
+import { MessageId, MessageSchema, Messages, WeakMessageData, WeakMessageSchema } from "./messages.js";
+//#region src/adapters/custom.d.ts
+export interface CustomAdapterOptions<S extends MessageSchema> extends Pick<LocolizeConfig, 'locales' | 'getLocale' | 'setLocale' | 'formatDraft' | 'variablesIn'> {
+  translate: (id: MessageId<S>, data: S[MessageId<S>]) => string;
+  /** Like `translate`, in any locale. Lets inline editing show every translation. */
+  translateIn?: ((id: MessageId<S>, data: S[MessageId<S>], locale: string) => string) | undefined;
+}
+/**
+ * Connects any string-keyed `t(id, data)`. `m.cart_items` becomes a function
+ * that calls `translate('cart_items', data)`.
+ */
+export declare function custom<S extends MessageSchema>({ translate, translateIn, ...config }: CustomAdapterOptions<S>): Adapter<Messages<S>>;
+//#endregion
+export type { MessageId, MessageSchema, Messages, WeakMessageData, WeakMessageSchema };

package/dist/adapters/custom.js

@@ -0,0 +1,18 @@
+import { createMessages, resolveId, uncheckedArgs } from "./messages.js";
+//#region src/adapters/custom.ts
+/**
+* Connects any string-keyed `t(id, data)`. `m.cart_items` becomes a function
+* that calls `translate('cart_items', data)`.
+*/
+function custom({ translate, translateIn, ...config }) {
+	return {
+		messages: createMessages(translate),
+		config: {
+			...config,
+			resolveId,
+			renderIn: translateIn ? (message, data, locale) => translateIn(...uncheckedArgs(resolveId(message), data), locale) : void 0
+		}
+	};
+}
+//#endregion
+export { custom };

package/dist/adapters/formatjs.d.ts

@@ -0,0 +1,15 @@
+import { Adapter } from "../types.js";
+import { MessageSchema, Messages, WeakMessageData, WeakMessageSchema } from "./messages.js";
+//#region src/adapters/formatjs.d.ts
+/**
+ * Connects ICU messages formatted with FormatJS, the engine behind
+ * react-intl. Owns the `IntlShape` per locale; drafts are ICU too, so plurals
+ * preview correctly while typing.
+ */
+export declare function formatjs<S extends MessageSchema>({ messages, locale: initial }: {
+  /** Locale → id → ICU message. */
+  messages: Record<string, Record<string, string>>;
+  locale: string;
+}): Adapter<Messages<S>>;
+//#endregion
+export type { MessageSchema, Messages, WeakMessageData, WeakMessageSchema };

package/dist/adapters/formatjs.js

@@ -0,0 +1,45 @@
+import { isRecord } from "../guards.js";
+import { custom } from "./custom.js";
+import { createIntl } from "@formatjs/intl";
+//#region src/adapters/formatjs.ts
+/** The data's string and number values, the ones ICU placeholders take. */
+function values(data) {
+	if (!isRecord(data)) return {};
+	return Object.fromEntries(Object.entries(data).filter((entry) => typeof entry[1] === "string" || typeof entry[1] === "number"));
+}
+/**
+* Connects ICU messages formatted with FormatJS, the engine behind
+* react-intl. Owns the `IntlShape` per locale; drafts are ICU too, so plurals
+* preview correctly while typing.
+*/
+function formatjs({ messages, locale: initial }) {
+	const intls = /* @__PURE__ */ new Map();
+	const intlFor = (locale) => {
+		let found = intls.get(locale);
+		if (!found) {
+			found = createIntl({
+				locale,
+				messages: messages[locale] ?? {}
+			});
+			intls.set(locale, found);
+		}
+		return found;
+	};
+	let intl = intlFor(initial);
+	return custom({
+		translate: (id, data) => intl.formatMessage({ id }, values(data)),
+		translateIn: (id, data, locale) => intlFor(locale).formatMessage({ id }, values(data)),
+		formatDraft: (template, data, locale) => createIntl({
+			locale,
+			messages: { draft: template },
+			onError: () => {}
+		}).formatMessage({ id: "draft" }, values(data)),
+		locales: Object.keys(messages),
+		getLocale: () => intl.locale,
+		setLocale: (locale) => {
+			intl = intlFor(locale);
+		}
+	});
+}
+//#endregion
+export { formatjs };

package/dist/adapters/i18next.d.ts

@@ -0,0 +1,11 @@
+import { Adapter } from "../types.js";
+import { MessageSchema, Messages, WeakMessageData, WeakMessageSchema } from "./messages.js";
+import { i18n } from "i18next";
+//#region src/adapters/i18next.d.ts
+/**
+ * Connects an initialized i18next instance. Locales come from its `resources`
+ * (or `supportedLngs`), drafts use its interpolation prefix and suffix.
+ */
+export declare function i18next<S extends MessageSchema>(i18n: i18n): Adapter<Messages<S>>;
+//#endregion
+export type { MessageSchema, Messages, WeakMessageData, WeakMessageSchema };

package/dist/adapters/i18next.js

@@ -0,0 +1,26 @@
+import { isRecord } from "../guards.js";
+import { delimited } from "../inline/variables.js";
+import { custom } from "./custom.js";
+//#region src/adapters/i18next.ts
+const options = (data) => isRecord(data) ? data : {};
+/**
+* Connects an initialized i18next instance. Locales come from its `resources`
+* (or `supportedLngs`), drafts use its interpolation prefix and suffix.
+*/
+function i18next(i18n) {
+	const { resources, supportedLngs, interpolation } = i18n.options;
+	const { interpolate, variablesIn } = delimited(interpolation?.prefix ?? "{{", interpolation?.suffix ?? "}}");
+	return custom({
+		translate: (id, data) => i18n.t(id, options(data)),
+		translateIn: (id, data, locale) => i18n.getFixedT(locale)(id, options(data)),
+		locales: resources ? Object.keys(resources) : supportedLngs === false || supportedLngs === void 0 ? [] : supportedLngs.filter((locale) => locale !== "cimode"),
+		getLocale: () => i18n.language,
+		setLocale: async (locale) => {
+			await i18n.changeLanguage(locale);
+		},
+		formatDraft: interpolate,
+		variablesIn
+	});
+}
+//#endregion
+export { i18next };

package/dist/adapters/messages.d.ts

@@ -0,0 +1,50 @@
+import { AnyMessage, MessageArgs } from "../types.js";
+//#region src/adapters/messages.d.ts
+/**
+ * Describes a string-keyed library's messages: `{ [id]: data }`.
+ * Use `undefined` for messages without parameters.
+ *
+ * @example
+ *   type AppMessages = {
+ *     welcome: undefined;
+ *     cart_items: { count: number };
+ *     sign_off: { name?: string }; // all-optional → data is optional too
+ *   };
+ */
+export type MessageSchema = object;
+/** Loose data for messages not (yet) described precisely: optional, any shape. */
+export type WeakMessageData = Record<string, unknown> | undefined;
+/**
+ * For gradual adoption: every message accepts optional, untyped data.
+ * Pass your keys to keep key checking, or omit them to allow any key.
+ * Intersect with a precise schema to tighten messages one by one.
+ *
+ * @example
+ *   type AppMessages = WeakMessageSchema<keyof typeof en> & {
+ *     cart_items: { count: number };
+ *   };
+ */
+export type WeakMessageSchema<K extends string = string> = Record<K, WeakMessageData>;
+export type MessageId<S extends MessageSchema> = Extract<keyof S, string>;
+declare const MESSAGE_ID: unique symbol;
+export type Messages<S extends MessageSchema> = { readonly [K in MessageId<S>]: ((...args: MessageArgs<S[K]>) => string) & {
+  readonly [MESSAGE_ID]: K;
+}; };
+/**
+ * Wraps any string-based `t(key, data)` so it can be used like Paraglide's `m`:
+ * `m.cart_items` is a function that calls `translate('cart_items', data)`.
+ * Each function is created once per key, so its identity is stable.
+ *
+ * @example
+ *   export const m = createMessages<AppMessages>((id, data) => i18next.t(id, data));
+ */
+export declare function createMessages<S extends MessageSchema>(translate: (id: MessageId<S>, data: S[MessageId<S>]) => string): Messages<S>;
+/**
+ * An id and data as `translate` expects them. Ids come from property names at
+ * runtime, while the schema only exists at the type level, so they can't be
+ * checked against it, only trusted.
+ */
+export declare function uncheckedArgs<S extends MessageSchema>(id: string, data: unknown): [id: MessageId<S>, data: S[MessageId<S>]];
+export declare function resolveId(message: AnyMessage): string;
+//#endregion
+export {};

package/dist/adapters/messages.js

@@ -0,0 +1,35 @@
+//#region src/adapters/messages.ts
+const MESSAGE_ID = Symbol.for("locolize.message-id");
+/**
+* Wraps any string-based `t(key, data)` so it can be used like Paraglide's `m`:
+* `m.cart_items` is a function that calls `translate('cart_items', data)`.
+* Each function is created once per key, so its identity is stable.
+*
+* @example
+*   export const m = createMessages<AppMessages>((id, data) => i18next.t(id, data));
+*/
+function createMessages(translate) {
+	const cache = /* @__PURE__ */ new Map();
+	const messageFor = (key) => {
+		let message = cache.get(key);
+		if (!message) {
+			message = Object.assign((data) => translate(...uncheckedArgs(key, data)), { [MESSAGE_ID]: key });
+			cache.set(key, message);
+		}
+		return message;
+	};
+	return new Proxy({}, { get: (_target, key) => typeof key === "string" && key !== "then" && !(key in Object.prototype) ? messageFor(key) : void 0 });
+}
+/**
+* An id and data as `translate` expects them. Ids come from property names at
+* runtime, while the schema only exists at the type level, so they can't be
+* checked against it, only trusted.
+*/
+function uncheckedArgs(id, data) {
+	return [id, data];
+}
+function resolveId(message) {
+	return MESSAGE_ID in message && typeof message[MESSAGE_ID] === "string" ? message[MESSAGE_ID] : "";
+}
+//#endregion
+export { createMessages, resolveId, uncheckedArgs };

package/dist/adapters/paraglide.d.ts

@@ -0,0 +1,16 @@
+import { Adapter } from "../types.js";
+//#region src/adapters/paraglide.d.ts
+/** The parts of Paraglide's generated `runtime.js` the adapter needs. */
+export interface ParaglideRuntime {
+  locales: readonly string[];
+  getLocale: () => string;
+  setLocale(locale: string, options?: {
+    reload?: boolean;
+  }): void | Promise<void>;
+}
+export declare function paraglide<M>({ messages, runtime }: {
+  /** The generated `m`. */
+  messages: M;
+  runtime: ParaglideRuntime;
+}): Adapter<M>;
+//#endregion

package/dist/adapters/paraglide.js

@@ -0,0 +1,15 @@
+//#region src/adapters/paraglide.ts
+function paraglide({ messages, runtime }) {
+	return {
+		messages,
+		config: {
+			resolveId: (message) => message.name,
+			locales: runtime.locales,
+			getLocale: runtime.getLocale,
+			setLocale: (locale) => runtime.setLocale(locale, { reload: false }),
+			renderIn: (message, data, locale) => message(data, { locale })
+		}
+	};
+}
+//#endregion
+export { paraglide };

package/dist/create.d.ts

@@ -0,0 +1,15 @@
+import { Adapter } from "./types.js";
+import { Locolize } from "./runtime.js";
+//#region src/create.d.ts
+/**
+ * Builds the runtime for an adapter. Call it once, at module level, and hand
+ * `locolize` to your framework's provider.
+ *
+ * @example
+ *   export const { m, locolize } = createLocolize(i18next<AppMessages>(i18n));
+ */
+export declare function createLocolize<M>(adapter: Adapter<M>): {
+  m: M;
+  locolize: Locolize;
+};
+//#endregion

package/dist/create.js

@@ -0,0 +1,17 @@
+import { createRuntime } from "#runtime";
+//#region src/create.ts
+/**
+* Builds the runtime for an adapter. Call it once, at module level, and hand
+* `locolize` to your framework's provider.
+*
+* @example
+*   export const { m, locolize } = createLocolize(i18next<AppMessages>(i18n));
+*/
+function createLocolize(adapter) {
+	return {
+		m: adapter.messages,
+		locolize: createRuntime(adapter.config)
+	};
+}
+//#endregion
+export { createLocolize };

package/dist/guards.d.ts

@@ -0,0 +1,6 @@
+//#region src/guards.d.ts
+/** Narrows `unknown` (parsed JSON, message data) to something with fields. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** A thrown value as an `Error`, since anything can be thrown. */
+export declare function toError(value: unknown): Error;
+//#endregion

package/dist/guards.js

@@ -0,0 +1,11 @@
+//#region src/guards.ts
+/** Narrows `unknown` (parsed JSON, message data) to something with fields. */
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/** A thrown value as an `Error`, since anything can be thrown. */
+function toError(value) {
+	return value instanceof Error ? value : new Error(String(value));
+}
+//#endregion
+export { isRecord, toError };

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { Adapter, AnyMessage, TranslateFn } from "./types.js";
+import { MessageSchema, Messages, WeakMessageData, WeakMessageSchema } from "./adapters/messages.js";
+import { Locolize } from "./runtime.js";
+import { createLocolize } from "./create.js";
+export { type Adapter, type AnyMessage, type Locolize, type MessageSchema, type Messages, type TranslateFn, type WeakMessageData, type WeakMessageSchema, createLocolize };

package/dist/index.js

@@ -0,0 +1 @@
+export { createLocolize } from "./create.js";

package/dist/inline/editor.d.ts

@@ -0,0 +1,37 @@
+import { Connection } from "./oauth.js";
+import { Files } from "./project.js";
+import { Store } from "../store.js";
+import { SessionApi } from "./session.js";
+//#region src/inline/editor.d.ts
+/** Locale → key → edited value. */
+export type Drafts = Record<string, Record<string, string>>;
+export interface Selection {
+  key: string;
+  /** The text it was opened from; the edit card sits next to it. */
+  anchor: Element;
+}
+export interface EditorState {
+  editing: boolean;
+  files: Files | null;
+  loadError: Error | null;
+  selected: Selection | null;
+  drafts: Drafts;
+  submitting: boolean;
+  submitError: Error | null;
+  submitted: boolean;
+}
+export interface EditorApi {
+  store: Store<EditorState>;
+  /** Starts loading the files on sign-in. Safe to call more than once. */
+  start: () => void;
+  setEditing: (editing: boolean) => void;
+  select: (selection: Selection | null) => void;
+  setDraft: (locale: string, key: string, value: string) => void;
+  /** Drops the key's drafts, in one locale or all. */
+  revert: (key: string, locale?: string) => void;
+  discard: () => void;
+  submit: () => void;
+}
+export declare function changeCount(drafts: Drafts): number;
+export declare function createEditor(connection: Connection, session: SessionApi): EditorApi;
+//#endregion

package/dist/inline/editor.js

@@ -0,0 +1,144 @@
+import { isRecord, toError } from "../guards.js";
+import { createStore } from "../store.js";
+import { RequestError, fetchFiles, submitFiles } from "./project.js";
+//#region src/inline/editor.ts
+const NO_DRAFTS = {};
+function changeCount(drafts) {
+	return Object.values(drafts).reduce((count, edits) => count + Object.keys(edits).length, 0);
+}
+function storageKey(connection) {
+	return `locolize:drafts:${connection.clientId}`;
+}
+function readDrafts(connection) {
+	try {
+		const stored = sessionStorage.getItem(storageKey(connection));
+		if (stored === null) return NO_DRAFTS;
+		const parsed = JSON.parse(stored);
+		return isDrafts(parsed) ? parsed : NO_DRAFTS;
+	} catch {
+		return NO_DRAFTS;
+	}
+}
+function isDrafts(value) {
+	return isRecord(value) && Object.values(value).every((edits) => isRecord(edits) && Object.values(edits).every((edit) => typeof edit === "string"));
+}
+function writeDrafts(connection, drafts) {
+	try {
+		if (Object.keys(drafts).length > 0) sessionStorage.setItem(storageKey(connection), JSON.stringify(drafts));
+		else sessionStorage.removeItem(storageKey(connection));
+	} catch {}
+}
+function createEditor(connection, session) {
+	const store = createStore({
+		editing: false,
+		files: null,
+		loadError: null,
+		selected: null,
+		drafts: readDrafts(connection),
+		submitting: false,
+		submitError: null,
+		submitted: false
+	});
+	const update = (patch) => store.set((current) => ({
+		...current,
+		...patch
+	}));
+	const setDrafts = (change) => {
+		const drafts = change(store.get().drafts);
+		update({ drafts });
+		writeDrafts(connection, drafts);
+	};
+	const load = async () => {
+		try {
+			const token = await session.getAccessToken();
+			if (token !== null) update({ files: await fetchFiles(connection, token) });
+		} catch (error) {
+			update({ loadError: toError(error) });
+		}
+	};
+	let signedIn = false;
+	const onSession = () => {
+		const now = Boolean(session.store.get().session);
+		if (now && !signedIn) load();
+		signedIn = now;
+	};
+	let started = false;
+	const start = () => {
+		if (started) return;
+		started = true;
+		session.store.subscribe(onSession);
+		onSession();
+	};
+	const submit = async () => {
+		const { files, drafts } = store.get();
+		const token = await session.getAccessToken();
+		if (files === null || token === null) return;
+		update({
+			submitting: true,
+			submitError: null
+		});
+		try {
+			const merged = Object.fromEntries(Object.entries(files).map(([locale, keys]) => [locale, {
+				...keys,
+				...drafts[locale]
+			}]));
+			await submitFiles(connection, token, merged);
+			update({
+				files: await fetchFiles(connection, token),
+				submitted: true
+			});
+			setDrafts(() => NO_DRAFTS);
+		} catch (error) {
+			if (!(error instanceof RequestError && error.status === 409)) {
+				update({ submitError: toError(error) });
+				return;
+			}
+			try {
+				update({
+					files: await fetchFiles(connection, token),
+					submitError: /* @__PURE__ */ new Error("Someone else submitted in the meantime. Their changes are loaded now. Check your edits and submit again.")
+				});
+			} catch (reloadError) {
+				update({ submitError: toError(reloadError) });
+			}
+		} finally {
+			update({ submitting: false });
+		}
+	};
+	return {
+		store,
+		start,
+		setEditing: (editing) => update({ editing }),
+		select: (selected) => update({ selected }),
+		setDraft(locale, key, value) {
+			update({ submitted: false });
+			const saved = store.get().files?.[locale]?.[key] ?? "";
+			setDrafts((current) => {
+				const edits = { ...current[locale] };
+				if (value === saved) delete edits[key];
+				else edits[key] = value;
+				const next = {
+					...current,
+					[locale]: edits
+				};
+				if (Object.keys(edits).length === 0) delete next[locale];
+				return next;
+			});
+		},
+		revert(key, locale) {
+			setDrafts((current) => {
+				const next = {};
+				for (const [draftLocale, edits] of Object.entries(current)) {
+					const { [key]: _, ...rest } = edits;
+					const kept = locale !== void 0 && draftLocale !== locale ? edits : rest;
+					if (Object.keys(kept).length > 0) next[draftLocale] = kept;
+				}
+				return next;
+			});
+		},
+		discard: () => setDrafts(() => NO_DRAFTS),
+		submit: () => void submit()
+	};
+}
+//#endregion
+export { changeCount, createEditor };

package/dist/inline/entry.d.ts

@@ -0,0 +1,4 @@
+import { RuntimeFactory } from "../runtime.js";
+//#region src/inline/entry.d.ts
+export declare const createRuntime: RuntimeFactory;
+//#endregion

package/dist/inline/entry.js

@@ -0,0 +1,6 @@
+import { createInlineLocolize } from "./runtime.js";
+import { connection } from "virtual:locolize/options";
+//#region src/inline/entry.ts
+const createRuntime = (config) => createInlineLocolize(config, { connection: connection ?? void 0 });
+//#endregion
+export { createRuntime };

package/dist/inline/oauth.d.ts

@@ -0,0 +1,20 @@
+//#region src/inline/oauth.d.ts
+export interface Connection {
+  /** From the project's settings on Locolize. */
+  clientId: string;
+  /** Where Locolize runs, e.g. `https://app.locolize.com`. */
+  url: string;
+}
+export interface Session {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch ms. */
+  expiresAt: number;
+  name: string;
+  scope: string;
+}
+export declare function refreshSession(connection: Connection, session: Session): Promise<Session>;
+export declare function login(connection: Connection): Promise<Session>;
+/** In the sign-in popup: hands the result to the opener. */
+export declare function completeLoginInPopup(): boolean;
+//#endregion

package/dist/inline/oauth.js

@@ -0,0 +1,118 @@
+import { isRecord } from "../guards.js";
+//#region src/inline/oauth.ts
+const SCOPE = "translations:write";
+const POPUP_NAME = "locolize-login";
+function base64Url(bytes) {
+	return btoa(String.fromCodePoint(...bytes)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+function randomString() {
+	return base64Url(crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32)));
+}
+async function s256(input) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+	return base64Url(new Uint8Array(digest));
+}
+function redirectUri() {
+	return `${window.location.origin}/`;
+}
+async function requestTokens(url, body) {
+	const response = await fetch(new URL("/api/oauth/token", url), {
+		method: "POST",
+		body: new URLSearchParams(body)
+	});
+	const json = await response.json();
+	if (!response.ok) {
+		const reason = isRecord(json) && typeof json["error"] === "string" ? json["error"] : response.status;
+		throw new Error(`Token request failed: ${reason}`);
+	}
+	if (!isRecord(json) || typeof json["access_token"] !== "string" || typeof json["refresh_token"] !== "string" || typeof json["expires_in"] !== "number" || typeof json["name"] !== "string" || typeof json["scope"] !== "string") throw new Error("Token request returned an unexpected response");
+	return {
+		accessToken: json["access_token"],
+		refreshToken: json["refresh_token"],
+		expiresAt: Date.now() + json["expires_in"] * 1e3,
+		name: json["name"],
+		scope: json["scope"]
+	};
+}
+function refreshSession(connection, session) {
+	return requestTokens(connection.url, {
+		grant_type: "refresh_token",
+		refresh_token: session.refreshToken,
+		client_id: connection.clientId
+	});
+}
+function waitForCallback(popup, state) {
+	return new Promise((resolve, reject) => {
+		const onMessage = (event) => {
+			const { data } = event;
+			if (event.source !== popup || event.origin !== window.location.origin || !isCallbackMessage(data) || data.state !== state) return;
+			cleanup();
+			if (data.code === null) reject(/* @__PURE__ */ new Error(`Sign-in failed: ${data.error ?? "unknown error"}`));
+			else resolve(data.code);
+		};
+		const closedPoll = window.setInterval(() => {
+			if (!popup.closed) return;
+			cleanup();
+			reject(/* @__PURE__ */ new Error("Sign-in window was closed"));
+		}, 500);
+		const cleanup = () => {
+			window.removeEventListener("message", onMessage);
+			window.clearInterval(closedPoll);
+		};
+		window.addEventListener("message", onMessage);
+	});
+}
+async function login(connection) {
+	const popup = window.open("", POPUP_NAME, "popup,width=520,height=720");
+	if (!popup) throw new Error("Sign-in window was blocked");
+	try {
+		const verifier = randomString();
+		const state = randomString();
+		const authorize = new URL("/oauth/authorize", connection.url);
+		authorize.search = new URLSearchParams({
+			client_id: connection.clientId,
+			redirect_uri: redirectUri(),
+			response_type: "code",
+			code_challenge: await s256(verifier),
+			code_challenge_method: "S256",
+			scope: SCOPE,
+			state
+		}).toString();
+		popup.location.href = authorize.href;
+		const code = await waitForCallback(popup, state);
+		return await requestTokens(connection.url, {
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: redirectUri(),
+			client_id: connection.clientId,
+			code_verifier: verifier
+		});
+	} finally {
+		popup.close();
+	}
+}
+function isCallbackMessage(value) {
+	return isRecord(value) && value["type"] === "locolize:oauth-callback" && typeof value["state"] === "string" && (typeof value["code"] === "string" || value["code"] === null) && (typeof value["error"] === "string" || value["error"] === null);
+}
+function isMessageTarget(value) {
+	return isRecord(value) && typeof value["postMessage"] === "function";
+}
+const landing = typeof window === "undefined" ? null : new URL(window.location.href);
+/** In the sign-in popup: hands the result to the opener. */
+function completeLoginInPopup() {
+	const opener = window.opener;
+	const params = landing?.searchParams;
+	const state = params?.get("state") ?? null;
+	const code = params?.get("code") ?? null;
+	const error = params?.get("error") ?? null;
+	if (!isMessageTarget(opener) || state === null || code === null && error === null) return false;
+	opener.postMessage({
+		type: "locolize:oauth-callback",
+		state,
+		code,
+		error
+	}, window.location.origin);
+	return true;
+}
+//#endregion
+export { completeLoginInPopup, login, refreshSession };

package/dist/inline/project.d.ts

@@ -0,0 +1,11 @@
+import { Connection } from "./oauth.js";
+//#region src/inline/project.d.ts
+/** Locale → key → saved value. */
+export type Files = Record<string, Record<string, unknown>>;
+export declare class RequestError extends Error {
+  readonly status: number;
+  constructor(status: number, message: string);
+}
+export declare function fetchFiles(connection: Connection, token: string): Promise<Files>;
+export declare function submitFiles(connection: Connection, token: string, files: Files): Promise<void>;
+//#endregion

package/dist/inline/project.js

@@ -0,0 +1,54 @@
+import { isRecord } from "../guards.js";
+//#region src/inline/project.ts
+function uuid(hex) {
+	return [
+		hex.slice(0, 8),
+		hex.slice(8, 12),
+		hex.slice(12, 16),
+		hex.slice(16, 20),
+		hex.slice(20)
+	].join("-");
+}
+function projectUrl({ clientId, url }, path = "") {
+	const team = uuid(clientId.slice(0, 32));
+	const project = uuid(clientId.slice(32));
+	return new URL(`/api/teams/${team}/projects/${project}${path}`, url);
+}
+var RequestError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+		this.name = "RequestError";
+	}
+};
+async function request(input, token, init = {}) {
+	const response = await fetch(input, {
+		...init,
+		headers: {
+			...init.body === void 0 ? {} : { "Content-Type": "application/json" },
+			Authorization: `Bearer ${token}`
+		}
+	});
+	if (!response.ok) {
+		const body = await response.json().catch(() => null);
+		throw new RequestError(response.status, isRecord(body) && typeof body["message"] === "string" ? body["message"] : `Request failed: ${response.status}`);
+	}
+	return response.json();
+}
+async function fetchFiles(connection, token) {
+	const response = await request(projectUrl(connection, "/provider/translation_files"), token);
+	if (!isRecord(response) || !isRecord(response["files"])) throw new Error("Unexpected response for translation files");
+	const files = {};
+	for (const [locale, result] of Object.entries(response["files"])) if (isRecord(result) && isRecord(result["ok"]) && isRecord(result["ok"]["keys"])) files[locale] = result["ok"]["keys"];
+	return files;
+}
+async function submitFiles(connection, token, files) {
+	const body = Object.fromEntries(Object.entries(files).map(([locale, keys]) => [locale, { keys }]));
+	await request(projectUrl(connection, "/provider/submit_translations"), token, {
+		method: "POST",
+		body: JSON.stringify(body)
+	});
+}
+//#endregion
+export { RequestError, fetchFiles, submitFiles };

package/dist/inline/runtime.d.ts

@@ -0,0 +1,51 @@
+import { AnyMessage, LocolizeConfig } from "../types.js";
+import { Locolize, Snapshot } from "../runtime.js";
+import { Connection } from "./oauth.js";
+import { SessionApi, SessionState } from "./session.js";
+import { EditorApi, EditorState } from "./editor.js";
+//#region src/inline/runtime.d.ts
+/** What a message was rendered with, so the overlay can show and edit it. */
+export interface MessageEntry {
+  message: AnyMessage;
+  data: unknown;
+}
+export interface InlineLocolizeOptions {
+  /** Enables signing in to Locolize and editing. */
+  connection?: Connection | undefined;
+}
+export interface InlineSnapshot extends Snapshot {
+  showKeys: boolean;
+  session: SessionState | null;
+  /** Null without a connection. Editing and selection are off while signed out. */
+  editor: EditorState | null;
+}
+/**
+ * The runtime with everything inline editing needs, without any framework.
+ * Its `t()` records the text it returns; the overlay renders its UI from it.
+ */
+export interface InlineRuntime extends Locolize<InlineSnapshot> {
+  setShowKeys: (showKeys: boolean) => void;
+  /** What a message shows, with the current draft if it has one. */
+  textOf: (message: AnyMessage, data: unknown, locale?: string) => {
+    text: string;
+    edited: boolean;
+  };
+  /** The message in `locale`, or undefined when the library can't tell. */
+  renderIn: (message: AnyMessage, data: unknown, locale: string) => string | undefined;
+  variablesIn: (template: string) => Set<string>;
+  /**
+   * Registers the element a message is rendered into. Returns the cleanup, so
+   * it fits a React ref callback, a Svelte action or a Vue directive as is.
+   */
+  track: (element: Element, entry: MessageEntry) => () => void;
+  /** Each tracked element on the page, so a hover can find what it shows. */
+  rendered: ReadonlyMap<Element, MessageEntry>;
+  /** The messages whose `t()` returned this text, by id. */
+  entriesForText: (text: string) => ReadonlyMap<string, MessageEntry>;
+  session: SessionApi | null;
+  editor: EditorApi | null;
+}
+export declare function createInlineLocolize(config: LocolizeConfig, { connection }?: InlineLocolizeOptions): InlineRuntime;
+/** Whether the runtime was built for inline editing. */
+export declare function isInlineRuntime(runtime: Locolize): runtime is InlineRuntime;
+//#endregion

package/dist/inline/runtime.js

@@ -0,0 +1,115 @@
+import { createStore } from "../store.js";
+import { createEditor } from "./editor.js";
+import { createSession } from "./session.js";
+import { interpolate, variablesIn } from "./variables.js";
+//#region src/inline/runtime.ts
+const NONE = /* @__PURE__ */ new Map();
+function createInlineLocolize(config, { connection } = {}) {
+	const session = connection ? createSession(connection) : null;
+	const editor = session && connection ? createEditor(connection, session) : null;
+	const own = createStore({
+		locale: config.getLocale(),
+		showKeys: false
+	});
+	const build = () => {
+		const signedIn = Boolean(session?.store.get().session);
+		const editorState = editor?.store.get();
+		return {
+			...own.get(),
+			session: session?.store.get() ?? null,
+			editor: editorState ? {
+				...editorState,
+				editing: editorState.editing && signedIn,
+				selected: signedIn ? editorState.selected : null
+			} : null
+		};
+	};
+	let snapshot = build();
+	const listeners = /* @__PURE__ */ new Set();
+	const onChange = () => {
+		snapshot = build();
+		for (const listener of Array.from(listeners)) listener();
+	};
+	own.subscribe(onChange);
+	session?.store.subscribe(onChange);
+	editor?.store.subscribe(onChange);
+	const rendered = /* @__PURE__ */ new Map();
+	const registry = /* @__PURE__ */ new Map();
+	const textOf = (message, data, locale) => {
+		const { showKeys, locale: current } = own.get();
+		if (showKeys) return {
+			text: config.resolveId(message),
+			edited: false
+		};
+		const target = locale ?? current;
+		const id = config.resolveId(message);
+		const format = config.formatDraft ?? interpolate;
+		const state = editor?.store.get();
+		const draft = state?.drafts[target]?.[id];
+		if (draft !== void 0) return {
+			text: format(draft, data, target),
+			edited: true
+		};
+		const saved = state?.files?.[target]?.[id];
+		if (typeof saved === "string") return {
+			text: format(saved, data, target),
+			edited: false
+		};
+		return {
+			text: (target === current ? message(data) : config.renderIn?.(message, data, target)) ?? "",
+			edited: false
+		};
+	};
+	function t(message, data) {
+		const { text } = textOf(message, data);
+		const entries = registry.get(text) ?? /* @__PURE__ */ new Map();
+		entries.set(config.resolveId(message), {
+			message,
+			data
+		});
+		registry.set(text, entries);
+		return text;
+	}
+	return {
+		config,
+		getSnapshot: () => snapshot,
+		subscribe(listener) {
+			editor?.start();
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		},
+		async setLocale(locale) {
+			await config.setLocale(locale);
+			own.set((current) => ({
+				...current,
+				locale: config.getLocale()
+			}));
+		},
+		setShowKeys: (showKeys) => own.set((current) => ({
+			...current,
+			showKeys
+		})),
+		t,
+		textOf,
+		renderIn: (message, data, locale) => locale === own.get().locale ? message(data) : config.renderIn?.(message, data, locale),
+		variablesIn: config.variablesIn ?? variablesIn,
+		track(element, entry) {
+			rendered.set(element, entry);
+			return () => {
+				if (rendered.get(element) === entry) rendered.delete(element);
+			};
+		},
+		rendered,
+		entriesForText: (text) => registry.get(text) ?? NONE,
+		session,
+		editor
+	};
+}
+/** Whether the runtime was built for inline editing. */
+function isInlineRuntime(runtime) {
+	return "track" in runtime;
+}
+//#endregion
+export { createInlineLocolize, isInlineRuntime };

package/dist/inline/session.d.ts

@@ -0,0 +1,17 @@
+import { Connection, Session } from "./oauth.js";
+import { Store } from "../store.js";
+//#region src/inline/session.d.ts
+export interface SessionState {
+  session: Session | null;
+  pending: boolean;
+  error: Error | null;
+}
+export interface SessionApi {
+  store: Store<SessionState>;
+  login: () => void;
+  logout: () => void;
+  /** Refreshed when needed; null when signed out. */
+  getAccessToken: () => Promise<string | null>;
+}
+export declare function createSession(connection: Connection): SessionApi;
+//#endregion

package/dist/inline/session.js

@@ -0,0 +1,73 @@
+import { isRecord, toError } from "../guards.js";
+import { createStore } from "../store.js";
+import { completeLoginInPopup, login, refreshSession } from "./oauth.js";
+//#region src/inline/session.ts
+const EXPIRY_MARGIN_MS = 3e4;
+function storageKey(connection) {
+	return `locolize:session:${connection.clientId}`;
+}
+function readSession(connection) {
+	try {
+		const stored = sessionStorage.getItem(storageKey(connection));
+		if (stored === null) return null;
+		const parsed = JSON.parse(stored);
+		return isSession(parsed) ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+function isSession(value) {
+	return isRecord(value) && typeof value["accessToken"] === "string" && typeof value["refreshToken"] === "string" && typeof value["expiresAt"] === "number" && typeof value["name"] === "string" && typeof value["scope"] === "string";
+}
+function writeSession(connection, session) {
+	try {
+		if (session) sessionStorage.setItem(storageKey(connection), JSON.stringify(session));
+		else sessionStorage.removeItem(storageKey(connection));
+	} catch {}
+}
+function createSession(connection) {
+	if (completeLoginInPopup()) window.close();
+	const store = createStore({
+		session: readSession(connection),
+		pending: false,
+		error: null
+	});
+	let refreshing = null;
+	const setSession = (session) => {
+		store.set((current) => ({
+			...current,
+			session
+		}));
+		writeSession(connection, session);
+	};
+	return {
+		store,
+		login() {
+			store.set((current) => ({
+				...current,
+				pending: true,
+				error: null
+			}));
+			login(connection).then(setSession).catch((error) => store.set((current) => ({
+				...current,
+				error: toError(error)
+			}))).finally(() => store.set((current) => ({
+				...current,
+				pending: false
+			})));
+		},
+		logout: () => setSession(null),
+		async getAccessToken() {
+			const current = store.get().session;
+			if (!current) return null;
+			if (current.expiresAt - EXPIRY_MARGIN_MS > Date.now()) return current.accessToken;
+			refreshing ??= refreshSession(connection, current).catch(() => null);
+			const next = await refreshing;
+			refreshing = null;
+			setSession(next);
+			return next?.accessToken ?? null;
+		}
+	};
+}
+//#endregion
+export { createSession };

package/dist/inline/variables.d.ts

@@ -0,0 +1,10 @@
+//#region src/inline/variables.d.ts
+/** Filling and finding variables written as `<prefix>name<suffix>`, e.g. `{{name}}`. */
+export declare function delimited(prefix: string, suffix: string): {
+  interpolate: (template: string, inputs: unknown) => string;
+  variablesIn: (text: string) => Set<string>;
+};
+export declare const interpolate: (template: string, inputs: unknown) => string, variablesIn: (text: string) => Set<string>;
+/** The variables a message was called with, as `{name}` placeholders. */
+export declare function placeholders(inputs: unknown): Record<string, string>;
+//#endregion

package/dist/inline/variables.js

@@ -0,0 +1,21 @@
+import { isRecord } from "../guards.js";
+//#region src/inline/variables.ts
+const escape = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+/** Filling and finding variables written as `<prefix>name<suffix>`, e.g. `{{name}}`. */
+function delimited(prefix, suffix) {
+	const variable = new RegExp(`${escape(prefix)}\\s*(\\w+)\\s*${escape(suffix)}`, "gu");
+	return {
+		interpolate(template, inputs) {
+			const values = isRecord(inputs) ? inputs : {};
+			return template.replaceAll(variable, (match, name) => name in values ? String(values[name]) : match);
+		},
+		variablesIn: (text) => new Set(Array.from(text.matchAll(variable), ([, name = ""]) => name))
+	};
+}
+const { interpolate, variablesIn } = delimited("{", "}");
+/** The variables a message was called with, as `{name}` placeholders. */
+function placeholders(inputs) {
+	return Object.fromEntries(Object.keys(isRecord(inputs) ? inputs : {}).map((name) => [name, `{${name}}`]));
+}
+//#endregion
+export { delimited, interpolate, placeholders, variablesIn };

package/dist/internal.d.ts

@@ -0,0 +1,10 @@
+import { Adapter, AnyMessage, IsAny, LocolizeConfig, MessageArgs, MessageData, TranslateFn } from "./types.js";
+import { Locolize, RuntimeFactory, Snapshot, createPlainRuntime } from "./runtime.js";
+import { Connection, Session } from "./inline/oauth.js";
+import { Files } from "./inline/project.js";
+import { Store, createStore } from "./store.js";
+import { SessionApi, SessionState } from "./inline/session.js";
+import { Drafts, EditorApi, EditorState, Selection, changeCount } from "./inline/editor.js";
+import { InlineLocolizeOptions, InlineRuntime, InlineSnapshot, MessageEntry, createInlineLocolize, isInlineRuntime } from "./inline/runtime.js";
+import { delimited, interpolate, placeholders, variablesIn } from "./inline/variables.js";
+export { Adapter, AnyMessage, type Connection, type Drafts, type EditorApi, type EditorState, type Files, InlineLocolizeOptions, InlineRuntime, InlineSnapshot, IsAny, Locolize, LocolizeConfig, MessageArgs, MessageData, MessageEntry, RuntimeFactory, type Selection, type Session, type SessionApi, type SessionState, Snapshot, Store, TranslateFn, changeCount, createInlineLocolize, createPlainRuntime, createStore, delimited, interpolate, isInlineRuntime, placeholders, variablesIn };

package/dist/internal.js

@@ -0,0 +1,6 @@
+import { createStore } from "./store.js";
+import { createPlainRuntime } from "./runtime.js";
+import { changeCount } from "./inline/editor.js";
+import { delimited, interpolate, placeholders, variablesIn } from "./inline/variables.js";
+import { createInlineLocolize, isInlineRuntime } from "./inline/runtime.js";
+export { changeCount, createInlineLocolize, createPlainRuntime, createStore, delimited, interpolate, isInlineRuntime, placeholders, variablesIn };

package/dist/runtime-plain.d.ts

@@ -0,0 +1,4 @@
+import { RuntimeFactory } from "./runtime.js";
+//#region src/runtime-plain.d.ts
+export declare const createRuntime: RuntimeFactory;
+//#endregion

package/dist/runtime-plain.js

@@ -0,0 +1,5 @@
+import { createPlainRuntime } from "./runtime.js";
+//#region src/runtime-plain.ts
+const createRuntime = createPlainRuntime;
+//#endregion
+export { createRuntime };

package/dist/runtime.d.ts

@@ -0,0 +1,21 @@
+import { LocolizeConfig, TranslateFn } from "./types.js";
+//#region src/runtime.d.ts
+export interface Snapshot {
+  locale: string;
+}
+/**
+ * What every framework package needs: the config, the current locale and `t`.
+ * They provide it through their own DI and re-render on `subscribe`. Inline
+ * editing extends it, so builds without it ship only this.
+ */
+export interface Locolize<S extends Snapshot = Snapshot> {
+  config: LocolizeConfig;
+  getSnapshot: () => S;
+  subscribe: (listener: () => void) => () => void;
+  setLocale: (locale: string) => Promise<void>;
+  t: TranslateFn;
+}
+export declare function createPlainRuntime(config: LocolizeConfig): Locolize;
+/** Builds the runtime; `#runtime` picks the plain or the inline one. */
+export type RuntimeFactory = (config: LocolizeConfig) => Locolize;
+//#endregion

package/dist/runtime.js

@@ -0,0 +1,21 @@
+import { createStore } from "./store.js";
+//#region src/runtime.ts
+function translate(message, ...args) {
+	return message(...args);
+}
+const t = translate;
+function createPlainRuntime(config) {
+	const store = createStore({ locale: config.getLocale() });
+	return {
+		config,
+		getSnapshot: store.get,
+		subscribe: store.subscribe,
+		async setLocale(locale) {
+			await config.setLocale(locale);
+			store.set({ locale: config.getLocale() });
+		},
+		t
+	};
+}
+//#endregion
+export { createPlainRuntime };

package/dist/store.d.ts

@@ -0,0 +1,13 @@
+//#region src/store.d.ts
+/**
+ * A value that tells its listeners when it changes. Follows the contract of
+ * React's `useSyncExternalStore`, so every framework can wrap it in its own
+ * reactivity: Vue `shallowRef`, Svelte `createSubscriber`, Solid `from()`.
+ */
+export interface Store<T> {
+  get: () => T;
+  set: (next: T | ((current: T) => T)) => void;
+  subscribe: (listener: () => void) => () => void;
+}
+export declare function createStore<T>(initial: T): Store<T>;
+//#endregion

package/dist/store.js

@@ -0,0 +1,29 @@
+//#region src/store.ts
+/**
+* Whether `set` got an updater. Don't store functions in a store: they'd be
+* called as updaters.
+*/
+function isUpdater(next) {
+	return typeof next === "function";
+}
+function createStore(initial) {
+	let value = initial;
+	const listeners = /* @__PURE__ */ new Set();
+	return {
+		get: () => value,
+		set(next) {
+			const resolved = isUpdater(next) ? next(value) : next;
+			if (Object.is(resolved, value)) return;
+			value = resolved;
+			for (const listener of Array.from(listeners)) listener();
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
+}
+//#endregion
+export { createStore };

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+//#region src/types.d.ts
+/**
+ * A message is any function that returns its translated string.
+ * Paraglide's compiled messages already are one; string-keyed libraries get
+ * them from `createMessages()`. Call sites reference them statically
+ * (`m.cart_items`), which is what keeps per-message tree-shaking intact.
+ */
+export type AnyMessage = (...args: any[]) => string;
+/** The data a message takes, read from its first parameter. `undefined` = none. */
+export type MessageData<F extends AnyMessage> = Parameters<F> extends [] ? undefined : Parameters<F> extends [(infer D)?, ...unknown[]] ? NonNullable<D> extends Record<string, never> ? undefined : D : undefined;
+/** True only for `any`, which would otherwise match every branch below. */
+export type IsAny<T> = 0 extends 1 & T ? true : false;
+/** The arguments after the message: none, optional or required data. */
+export type MessageArgs<D> = IsAny<D> extends true ? [data?: unknown] : [D] extends [undefined] ? [] : undefined extends D ? [data?: Exclude<D, undefined>] : {} extends D ? [data?: D] : [data: D];
+export type TranslateFn = <F extends AnyMessage>(message: F, ...args: MessageArgs<MessageData<F>>) => string;
+export interface LocolizeConfig {
+  resolveId: (message: AnyMessage) => string;
+  /** Every locale the app can switch to. */
+  locales: readonly string[];
+  /** The library's current locale. */
+  getLocale: () => string;
+  /** Switches the library's locale; adapters re-render once it settles. */
+  setLocale: (locale: string) => void | Promise<void>;
+  /**
+   * Renders a message in any locale, not just the current one. Inline editing
+   * uses it to list all translations and to hint at missing ones; without it,
+   * only the current locale is shown.
+   */
+  renderIn?: ((message: AnyMessage, data: unknown, locale: string) => string) | undefined;
+  /**
+   * Fills a draft's variables to preview it in place. Defaults to replacing
+   * `{name}` placeholders; libraries with other syntax (`{{name}}`, ICU) pass
+   * their own.
+   */
+  formatDraft?: ((template: string, data: unknown, locale: string) => string) | undefined;
+  /** The variable names a draft uses, to warn about missing ones. Defaults to `{name}`. */
+  variablesIn?: ((template: string) => Set<string>) | undefined;
+}
+/**
+ * Connects an i18n library: its messages and how Locolize drives it. Made by
+ * the functions in `@thekatze/locolize-core/adapters/*`.
+ */
+export interface Adapter<M> {
+  messages: M;
+  config: LocolizeConfig;
+}
+//#endregion

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@thekatze/locolize-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-test.0",
+  "description": "Locolize runtime and i18n library adapters (Paraglide, i18next, FormatJS, custom).",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/enXess-ag/locolize-js.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./adapters/custom": {
+      "types": "./dist/adapters/custom.d.ts",
+      "default": "./dist/adapters/custom.js"
+    },
+    "./adapters/paraglide": {
+      "types": "./dist/adapters/paraglide.d.ts",
+      "default": "./dist/adapters/paraglide.js"
+    },
+    "./adapters/i18next": {
+      "types": "./dist/adapters/i18next.d.ts",
+      "default": "./dist/adapters/i18next.js"
+    },
+    "./adapters/formatjs": {
+      "types": "./dist/adapters/formatjs.d.ts",
+      "default": "./dist/adapters/formatjs.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    }
+  },
+  "imports": {
+    "#runtime": {
+      "locolize-inline": "./dist/inline/entry.js",
+      "default": "./dist/runtime-plain.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@formatjs/intl": "^6.0.0",
+    "i18next": ">=23"
+  },
+  "peerDependenciesMeta": {
+    "@formatjs/intl": {
+      "optional": true
+    },
+    "i18next": {
+      "optional": true
+    }
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.