@immediately-run/sdk 0.1.5 → 0.2.0

package/dist/theme.d.cts

@@ -0,0 +1,38 @@
+/**
+ * The host UI theme, mirrored from the immediately.run host window into the
+ * sandbox. Your app can read this to render in step with the host chrome
+ * (light / dark).
+ *
+ * This is the baseline `theme:read` capability — every app may read it. Changing
+ * the host theme is a separate, elevated action (`theme:set`), available only to
+ * the theme-toggle system app.
+ */
+type HostTheme = 'light' | 'dark';
+/**
+ * Returns the current host theme. Poll this for a one-off read; use
+ * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.
+ */
+declare const getHostTheme: () => HostTheme;
+/**
+ * Subscribe to host theme changes. The listener is invoked immediately with the
+ * current theme, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onHostThemeChange: (listener: (theme: HostTheme) => void) => (() => void);
+/**
+ * React hook returning the current host theme, re-rendering when it changes.
+ * The recommended way to implement an app's own `useTheme`: follow the host,
+ * allow a local override.
+ */
+declare const useHostTheme: () => HostTheme;
+/**
+ * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host
+ * applies it and re-pushes the new value to every `theme:read` iframe, so your
+ * own {@link useHostTheme} confirms the change (the loop closes with no special
+ * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may
+ * call this; any other app is rejected host-side with a `forbidden`
+ * {@link Error} (carrying `.code`), regardless of what the app claims. Update
+ * optimistically and let the re-push confirm.
+ */
+declare const setHostTheme: (theme: HostTheme) => Promise<void>;
+
+export { type HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme };

package/dist/theme.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The host UI theme, mirrored from the immediately.run host window into the
+ * sandbox. Your app can read this to render in step with the host chrome
+ * (light / dark).
+ *
+ * This is the baseline `theme:read` capability — every app may read it. Changing
+ * the host theme is a separate, elevated action (`theme:set`), available only to
+ * the theme-toggle system app.
+ */
+type HostTheme = 'light' | 'dark';
+/**
+ * Returns the current host theme. Poll this for a one-off read; use
+ * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.
+ */
+declare const getHostTheme: () => HostTheme;
+/**
+ * Subscribe to host theme changes. The listener is invoked immediately with the
+ * current theme, then again on every change. Returns an unsubscribe fn.
+ */
+declare const onHostThemeChange: (listener: (theme: HostTheme) => void) => (() => void);
+/**
+ * React hook returning the current host theme, re-rendering when it changes.
+ * The recommended way to implement an app's own `useTheme`: follow the host,
+ * allow a local override.
+ */
+declare const useHostTheme: () => HostTheme;
+/**
+ * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host
+ * applies it and re-pushes the new value to every `theme:read` iframe, so your
+ * own {@link useHostTheme} confirms the change (the loop closes with no special
+ * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may
+ * call this; any other app is rejected host-side with a `forbidden`
+ * {@link Error} (carrying `.code`), regardless of what the app claims. Update
+ * optimistically and let the re-push confirm.
+ */
+declare const setHostTheme: (theme: HostTheme) => Promise<void>;
+
+export { type HostTheme, getHostTheme, onHostThemeChange, setHostTheme, useHostTheme };

package/dist/theme.js

@@ -0,0 +1,30 @@
+import { useEffect, useState } from "react";
+import { protocolRequest } from "./sandboxUtils";
+const themeService = () => {
+  return module.evaluation.module.bundler.theme;
+};
+const getHostTheme = () => themeService().getTheme();
+const onHostThemeChange = (listener) => {
+  const disposable = themeService().onChange(listener);
+  return () => disposable.dispose();
+};
+const useHostTheme = () => {
+  const [theme, setTheme] = useState(getHostTheme);
+  useEffect(() => onHostThemeChange(setTheme), []);
+  return theme;
+};
+const setHostTheme = async (theme) => {
+  const res = await protocolRequest("theme", "set", [{ theme }]);
+  if (!res || res.ok !== true) {
+    const err = new Error(res?.message ?? "setHostTheme failed");
+    err.code = (res && "code" in res ? res.code : void 0) ?? "unknown";
+    throw err;
+  }
+};
+export {
+  getHostTheme,
+  onHostThemeChange,
+  setHostTheme,
+  useHostTheme
+};
+//# sourceMappingURL=theme.js.map

package/dist/theme.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme.ts"],"sourcesContent":["import { useEffect, useState } from 'react';\nimport { protocolRequest } from './sandboxUtils';\n\n/**\n * The host UI theme, mirrored from the immediately.run host window into the\n * sandbox. Your app can read this to render in step with the host chrome\n * (light / dark).\n *\n * This is the baseline `theme:read` capability — every app may read it. Changing\n * the host theme is a separate, elevated action (`theme:set`), available only to\n * the theme-toggle system app.\n */\nexport type HostTheme = 'light' | 'dark';\n\ninterface ThemeService {\n  getTheme(): HostTheme;\n  onChange(listener: (theme: HostTheme) => void): { dispose(): void };\n}\n\n// `module.evaluation.module.bundler.theme` is the sandbox bundler injected into\n// the evaluation context (same path the other SDK helpers use for `auth`).\nconst themeService = (): ThemeService => {\n  // @ts-ignore - injected by the sandbox runtime\n  return module.evaluation.module.bundler.theme;\n};\n\n/**\n * Returns the current host theme. Poll this for a one-off read; use\n * {@link onHostThemeChange} or {@link useHostTheme} to react to changes.\n */\nexport const getHostTheme = (): HostTheme => themeService().getTheme();\n\n/**\n * Subscribe to host theme changes. The listener is invoked immediately with the\n * current theme, then again on every change. Returns an unsubscribe fn.\n */\nexport const onHostThemeChange = (\n  listener: (theme: HostTheme) => void,\n): (() => void) => {\n  const disposable = themeService().onChange(listener);\n  return () => disposable.dispose();\n};\n\n/**\n * React hook returning the current host theme, re-rendering when it changes.\n * The recommended way to implement an app's own `useTheme`: follow the host,\n * allow a local override.\n */\nexport const useHostTheme = (): HostTheme => {\n  const [theme, setTheme] = useState<HostTheme>(getHostTheme);\n  useEffect(() => onHostThemeChange(setTheme), []);\n  return theme;\n};\n\n/**\n * Set the host UI theme — the ELEVATED `theme:set` action (§8.5). The host\n * applies it and re-pushes the new value to every `theme:read` iframe, so your\n * own {@link useHostTheme} confirms the change (the loop closes with no special\n * case). Only a grant holding `theme:set` (e.g. the theme-toggle system app) may\n * call this; any other app is rejected host-side with a `forbidden`\n * {@link Error} (carrying `.code`), regardless of what the app claims. Update\n * optimistically and let the re-push confirm.\n */\nexport const setHostTheme = async (theme: HostTheme): Promise<void> => {\n  const res = (await protocolRequest('theme', 'set', [{ theme }])) as\n    | { ok: true; data?: unknown }\n    | { ok: false; code?: string; message?: string }\n    | undefined;\n  if (!res || res.ok !== true) {\n    const err = new Error(res?.message ?? 'setHostTheme failed') as Error & {\n      code?: string;\n    };\n    err.code = (res && 'code' in res ? res.code : undefined) ?? 'unknown';\n    throw err;\n  }\n};\n"],"mappings":"AAAA,SAAS,WAAW,gBAAgB;AACpC,SAAS,uBAAuB;AAoBhC,MAAM,eAAe,MAAoB;AAEvC,SAAO,OAAO,WAAW,OAAO,QAAQ;AAC1C;AAMO,MAAM,eAAe,MAAiB,aAAa,EAAE,SAAS;AAM9D,MAAM,oBAAoB,CAC/B,aACiB;AACjB,QAAM,aAAa,aAAa,EAAE,SAAS,QAAQ;AACnD,SAAO,MAAM,WAAW,QAAQ;AAClC;AAOO,MAAM,eAAe,MAAiB;AAC3C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAoB,YAAY;AAC1D,YAAU,MAAM,kBAAkB,QAAQ,GAAG,CAAC,CAAC;AAC/C,SAAO;AACT;AAWO,MAAM,eAAe,OAAO,UAAoC;AACrE,QAAM,MAAO,MAAM,gBAAgB,SAAS,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;AAI9D,MAAI,CAAC,OAAO,IAAI,OAAO,MAAM;AAC3B,UAAM,MAAM,IAAI,MAAM,KAAK,WAAW,qBAAqB;AAG3D,QAAI,QAAQ,OAAO,UAAU,MAAM,IAAI,OAAO,WAAc;AAC5D,UAAM;AAAA,EACR;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",