@proteos/component-sdk 0.18.1

package/LICENSE

@@ -0,0 +1,40 @@
+PROPRIETARY AND CONFIDENTIAL
+
+Copyright (c) 2026 Proteos. All rights reserved.
+
+This software, including all source code, object code, documentation, designs,
+and any other materials contained in this repository (the "Software"), is the
+proprietary and confidential property of Proteos.
+
+NO LICENSE IS GRANTED. The Software is made available solely for internal use
+by Proteos and its authorized employees, contractors, and agents under the
+terms of their respective agreements with Proteos.
+
+Without the express prior written permission of Proteos, you may not, in whole
+or in part:
+
+  1. copy, reproduce, mirror, host, or store the Software;
+  2. modify, adapt, translate, or create derivative works of the Software;
+  3. distribute, publish, transmit, sublicense, sell, rent, lease, or
+     otherwise transfer or make the Software available to any third party;
+  4. reverse engineer, decompile, disassemble, or attempt to derive the
+     source code, structure, or organization of any compiled portion of the
+     Software, except to the extent that such activity is expressly permitted
+     by applicable law notwithstanding this restriction;
+  5. remove, obscure, or alter any proprietary notices, labels, or marks
+     contained in the Software; or
+  6. use the Software, or any information derived from it, to develop or
+     improve a competing product or service.
+
+Any unauthorized use, reproduction, or disclosure of the Software constitutes
+a material breach of this license, may infringe Proteos' intellectual property
+rights, and may violate applicable laws.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT. IN NO EVENT
+SHALL PROTEOS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For licensing inquiries, contact: legal@proteos.io

package/dist/chunk-NMXHDDL6.js

@@ -0,0 +1,12 @@
+// src/protocol.ts
+var MESSAGE_SOURCE = "proteos-component-runtime";
+function isHostMessage(data) {
+  return typeof data === "object" && data !== null && data.source === MESSAGE_SOURCE && typeof data.type === "string";
+}
+function isRuntimeMessage(data) {
+  return typeof data === "object" && data !== null && data.source === MESSAGE_SOURCE && typeof data.type === "string";
+}
+
+export { MESSAGE_SOURCE, isHostMessage, isRuntimeMessage };
+//# sourceMappingURL=chunk-NMXHDDL6.js.map
+//# sourceMappingURL=chunk-NMXHDDL6.js.map

package/dist/chunk-NMXHDDL6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";AAUO,IAAM,cAAA,GAAiB;AA4EvB,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-NMXHDDL6.js","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value. */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\nexport type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}

package/dist/chunk-SMAZA2KE.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+// src/protocol.ts
+var MESSAGE_SOURCE = "proteos-component-runtime";
+function isHostMessage(data) {
+  return typeof data === "object" && data !== null && data.source === MESSAGE_SOURCE && typeof data.type === "string";
+}
+function isRuntimeMessage(data) {
+  return typeof data === "object" && data !== null && data.source === MESSAGE_SOURCE && typeof data.type === "string";
+}
+
+exports.MESSAGE_SOURCE = MESSAGE_SOURCE;
+exports.isHostMessage = isHostMessage;
+exports.isRuntimeMessage = isRuntimeMessage;
+//# sourceMappingURL=chunk-SMAZA2KE.cjs.map
+//# sourceMappingURL=chunk-SMAZA2KE.cjs.map

package/dist/chunk-SMAZA2KE.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/protocol.ts"],"names":[],"mappings":";;;AAUO,IAAM,cAAA,GAAiB;AA4EvB,SAAS,cAAc,IAAA,EAA8C;AAC1E,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD;AAEO,SAAS,iBAAiB,IAAA,EAAiD;AAChF,EAAA,OACE,OAAO,IAAA,KAAS,QAAA,IAChB,IAAA,KAAS,IAAA,IACR,KAA8B,MAAA,KAAW,cAAA,IAC1C,OAAQ,IAAA,CAA4B,IAAA,KAAS,QAAA;AAEjD","file":"chunk-SMAZA2KE.cjs","sourcesContent":["// postMessage protocol between the host page and the component-runtime iframe.\n// This is the single source of truth for the wire contract: the host renderer\n// (clients/web .../component-frame.tsx), the runtime shell\n// (clients/web/component-runtime/shell.tsx), and the author-facing hooks\n// (this package's RuntimeProvider / useNavigate) all import these same types so\n// every end stays in lockstep.\n//\n// Every message carries `source: MESSAGE_SOURCE` so we can ignore the unrelated\n// postMessage traffic that shares the window (OIDC silent-renew, Vite HMR, …).\n\nexport const MESSAGE_SOURCE = 'proteos-component-runtime' as const\n\nexport interface PageContext {\n  record?: Record<string, unknown>\n  entity?: { slug: string; [key: string]: unknown }\n  params?: Record<string, unknown>\n  [key: string]: unknown\n}\n\n// ── Host → runtime ──────────────────────────────────────────────────────────\n\nexport interface InitMessage {\n  type: 'INIT'\n  /** Raw bearer token (the OIDC `id_token`). The runtime's ProteosClient\n   *  prepends `Bearer ` when building the Authorization header, so the host\n   *  sends the token verbatim — NOT a full `Bearer …` header value. */\n  authToken: string\n  /** API origin the bundle endpoint + SDK calls resolve against. */\n  apiBaseUrl: string\n  /** Resolved props for the component (Liquid templating happens host-side). */\n  props: Record<string, unknown>\n  pageCtx: PageContext\n}\n\nexport interface AuthRefreshMessage {\n  type: 'AUTH_REFRESH'\n  token: string\n}\n\nexport interface DataInvalidateMessage {\n  type: 'DATA_INVALIDATE'\n  queryKey?: unknown[]\n}\n\nexport type HostMessage = InitMessage | AuthRefreshMessage | DataInvalidateMessage\n\n// ── Runtime → host ──────────────────────────────────────────────────────────\n\nexport interface ReadyMessage {\n  type: 'READY'\n}\n\nexport interface ResizeMessage {\n  type: 'RESIZE'\n  height: number\n}\n\nexport interface NavigateMessage {\n  type: 'NAVIGATE'\n  to: string\n}\n\n/** Open an in-app path in a peek (slide-over) panel instead of full-page\n *  navigation. Same `/…` in-app path grammar as NAVIGATE; the host decides\n *  what can peek (today: platform pages) and falls back to NAVIGATE otherwise. */\nexport interface OpenPeekMessage {\n  type: 'OPEN_PEEK'\n  to: string\n}\n\nexport interface ErrorMessage {\n  type: 'ERROR'\n  message: string\n  stack?: string\n}\n\nexport type RuntimeMessage =\n  | ReadyMessage\n  | ResizeMessage\n  | NavigateMessage\n  | OpenPeekMessage\n  | ErrorMessage\n\n// Wire envelope: the message plus the source discriminator.\nexport type Envelope<T> = T & { source: typeof MESSAGE_SOURCE }\n\nexport function isHostMessage(data: unknown): data is Envelope<HostMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n\nexport function isRuntimeMessage(data: unknown): data is Envelope<RuntimeMessage> {\n  return (\n    typeof data === 'object' &&\n    data !== null &&\n    (data as { source?: unknown }).source === MESSAGE_SOURCE &&\n    typeof (data as { type?: unknown }).type === 'string'\n  )\n}\n"]}

package/dist/index.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+var chunkSMAZA2KE_cjs = require('./chunk-SMAZA2KE.cjs');
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+var RuntimeContext = react.createContext(null);
+function postNavigate(to) {
+  const envelope = { source: chunkSMAZA2KE_cjs.MESSAGE_SOURCE, type: "NAVIGATE", to };
+  window.parent?.postMessage(envelope, "*");
+}
+function postOpenPeek(to) {
+  const envelope = { source: chunkSMAZA2KE_cjs.MESSAGE_SOURCE, type: "OPEN_PEEK", to };
+  window.parent?.postMessage(envelope, "*");
+}
+function navigate(to, options) {
+  if (options?.peek) postOpenPeek(to);
+  else postNavigate(to);
+}
+function RuntimeProvider({ value, children }) {
+  const ctx = react.useMemo(() => ({ ...value, navigate }), [value]);
+  return /* @__PURE__ */ jsxRuntime.jsx(RuntimeContext.Provider, { value: ctx, children });
+}
+function useRuntime() {
+  const ctx = react.useContext(RuntimeContext);
+  if (!ctx) {
+    throw new Error(
+      "@proteos/component-sdk: hooks must run inside the Proteos component runtime. This usually means the component is rendered outside its iframe, or a second copy of @proteos/component-sdk was bundled instead of using the runtime-provided one (keep it external)."
+    );
+  }
+  return ctx;
+}
+function useSdk() {
+  return useRuntime().sdk;
+}
+function useProps() {
+  return useRuntime().props;
+}
+function usePageContext() {
+  return useRuntime().pageCtx;
+}
+function useNavigate() {
+  return useRuntime().navigate;
+}
+function useApiBaseUrl() {
+  return useRuntime().apiBaseUrl;
+}
+function useAuthToken() {
+  return useRuntime().getToken;
+}
+function readHostLocation() {
+  const empty = { pathname: null, orgId: null, appBasePath: null };
+  try {
+    const parentWindow = window.parent;
+    if (!parentWindow || parentWindow === window) return empty;
+    const pathname = parentWindow.location.pathname;
+    const appMatch = pathname.match(/^\/org\/[^/]+\/app\/[^/]+/);
+    const orgMatch = pathname.match(/^\/org\/([^/]+)\//);
+    return {
+      pathname,
+      orgId: orgMatch ? orgMatch[1] ?? null : null,
+      appBasePath: appMatch ? appMatch[0] : null
+    };
+  } catch {
+    return empty;
+  }
+}
+function useHostLocation() {
+  const [loc] = react.useState(readHostLocation);
+  return loc;
+}
+function useFillViewportHeight(options = {}) {
+  const { bottomMargin = 24, minHeight = 320 } = options;
+  const [height, setHeight] = react.useState(null);
+  react.useEffect(() => {
+    function compute() {
+      try {
+        const frame = window.frameElement;
+        const parentWindow = window.parent;
+        if (!frame || !parentWindow || parentWindow === window) return;
+        const available = parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin;
+        setHeight(Math.max(available, minHeight));
+      } catch {
+        setHeight(null);
+      }
+    }
+    compute();
+    try {
+      window.parent.addEventListener("resize", compute);
+      return () => window.parent.removeEventListener("resize", compute);
+    } catch {
+      return;
+    }
+  }, [bottomMargin, minHeight]);
+  return height;
+}
+
+Object.defineProperty(exports, "MESSAGE_SOURCE", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.MESSAGE_SOURCE; }
+});
+Object.defineProperty(exports, "isHostMessage", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.isHostMessage; }
+});
+Object.defineProperty(exports, "isRuntimeMessage", {
+  enumerable: true,
+  get: function () { return chunkSMAZA2KE_cjs.isRuntimeMessage; }
+});
+exports.RuntimeProvider = RuntimeProvider;
+exports.useApiBaseUrl = useApiBaseUrl;
+exports.useAuthToken = useAuthToken;
+exports.useFillViewportHeight = useFillViewportHeight;
+exports.useHostLocation = useHostLocation;
+exports.useNavigate = useNavigate;
+exports.usePageContext = usePageContext;
+exports.useProps = useProps;
+exports.useRuntime = useRuntime;
+exports.useSdk = useSdk;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":["createContext","MESSAGE_SOURCE","useMemo","useContext","useState","useEffect"],"mappings":"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","file":"index.cjs","sourcesContent":["import type {\n  AccountClient,\n  AgentClient,\n  DataClient,\n  FunctionsClient,\n  KnowledgeClient,\n  MetaClient,\n  StorageClient,\n} from '@proteos/sdk'\nimport { createContext, type ReactNode, useMemo } from 'react'\n\nimport {\n  type Envelope,\n  MESSAGE_SOURCE,\n  type NavigateMessage,\n  type OpenPeekMessage,\n  type PageContext,\n} from './protocol'\n\n/** Options for {@link RuntimeContextValue.navigate}. */\nexport interface NavigateOptions {\n  /** Open the target in a peek (slide-over) panel instead of full-page. */\n  peek?: boolean\n}\n\n/**\n * The authenticated `@proteos/sdk` clients the runtime injects. Same instances\n * the host app uses — pre-wired with a refreshing bearer token, so a component\n * never touches auth headers.\n */\nexport interface ComponentSdk {\n  account: AccountClient\n  agents: AgentClient\n  data: DataClient\n  functions: FunctionsClient\n  knowledge: KnowledgeClient\n  meta: MetaClient\n  storage: StorageClient\n}\n\n/**\n * The raw runtime payload the shell hands a component at INIT. The shell builds\n * this; component authors read it through the hooks.\n */\nexport interface RuntimeValue {\n  sdk: ComponentSdk\n  /** Liquid-resolved props (a snapshot — not a live binding). */\n  props: Record<string, unknown>\n  /** Page context snapshot: the host record, entity, and URL params. */\n  pageCtx: PageContext\n  /** API origin SDK calls + asset URLs resolve against. */\n  apiBaseUrl: string\n  /** Current bearer token getter (escape hatch for raw fetches). */\n  getToken: () => string\n}\n\n/** Runtime value plus the derived helpers the hooks expose. */\nexport interface RuntimeContextValue extends RuntimeValue {\n  /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or\n   *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */\n  navigate: (to: string, options?: NavigateOptions) => void\n}\n\nexport const RuntimeContext = createContext<RuntimeContextValue | null>(null)\n\n/** Post a NAVIGATE envelope to the host. The host only honours relative,\n *  in-app targets (it ignores absolute/external URLs). */\nfunction postNavigate(to: string): void {\n  const envelope: Envelope<NavigateMessage> = { source: MESSAGE_SOURCE, type: 'NAVIGATE', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Post an OPEN_PEEK envelope to the host — open the in-app path in a peek\n *  panel. Same relative-path contract as {@link postNavigate}. */\nfunction postOpenPeek(to: string): void {\n  const envelope: Envelope<OpenPeekMessage> = { source: MESSAGE_SOURCE, type: 'OPEN_PEEK', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */\nfunction navigate(to: string, options?: NavigateOptions): void {\n  if (options?.peek) postOpenPeek(to)\n  else postNavigate(to)\n}\n\n/**\n * Provides the runtime value + derived helpers to a component subtree. Mounted\n * by the component-runtime shell around the loaded component — authors never\n * render this themselves. Lives in `@proteos/component-sdk` (a shared,\n * import-mapped singleton) so the context the shell provides is the very same\n * context the component's hooks read, across the bundle boundary.\n */\nexport function RuntimeProvider({ value, children }: { value: RuntimeValue; children: ReactNode }) {\n  // The shell builds `value` once at INIT (a stable state object — clients,\n  // props and pageCtx are all set once), so memoizing on its identity recreates\n  // the context only when the runtime genuinely re-inits.\n  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate }), [value])\n  return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>\n}\n","import { useContext, useEffect, useState } from 'react'\n\nimport {\n  type ComponentSdk,\n  type NavigateOptions,\n  RuntimeContext,\n  type RuntimeContextValue,\n} from './context'\nimport type { PageContext } from './protocol'\n\n/**\n * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,\n * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a\n * clear error if used outside the component runtime.\n */\nexport function useRuntime(): RuntimeContextValue {\n  const ctx = useContext(RuntimeContext)\n  if (!ctx) {\n    throw new Error(\n      '@proteos/component-sdk: hooks must run inside the Proteos component runtime. ' +\n        'This usually means the component is rendered outside its iframe, or a ' +\n        'second copy of @proteos/component-sdk was bundled instead of using the ' +\n        'runtime-provided one (keep it external).',\n    )\n  }\n  return ctx\n}\n\n/** The authenticated SDK clients (account / data / functions / meta). */\nexport function useSdk(): ComponentSdk {\n  return useRuntime().sdk\n}\n\n/** The component's Liquid-resolved props (a snapshot, not a live binding). */\nexport function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T {\n  return useRuntime().props as T\n}\n\n/**\n * The full page context: host `record`, `entity`, and URL `params`. The\n * `record` is a snapshot taken at mount (`undefined` on record-less platform\n * pages) — fetch via `useSdk().data` for anything that must stay fresh.\n */\nexport function usePageContext(): PageContext {\n  return useRuntime().pageCtx\n}\n\n/**\n * Navigate the host SPA to an in-app path, e.g.\n * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external\n * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.\n *\n * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead\n * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host\n * peeks what it can (today: platform pages) and falls back to full navigation.\n */\nexport function useNavigate(): (to: string, options?: NavigateOptions) => void {\n  return useRuntime().navigate\n}\n\n/** The API origin SDK calls resolve against (for building raw asset URLs). */\nexport function useApiBaseUrl(): string {\n  return useRuntime().apiBaseUrl\n}\n\n/**\n * A getter for the current bearer token. Returns a function (not the token)\n * because the token is refreshed in place — read it at call time for a raw\n * `fetch`. Most components never need this; prefer `useSdk()`.\n */\nexport function useAuthToken(): () => string {\n  return useRuntime().getToken\n}\n\nexport interface HostLocation {\n  /** The host tab's pathname (same-origin read), or null if unavailable. */\n  pathname: string | null\n  /** The org id parsed from `/org/<orgId>/…`, or null. */\n  orgId: string | null\n  /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */\n  appBasePath: string | null\n}\n\nfunction readHostLocation(): HostLocation {\n  const empty: HostLocation = { pathname: null, orgId: null, appBasePath: null }\n  try {\n    const parentWindow = window.parent\n    if (!parentWindow || parentWindow === window) return empty\n    const pathname = parentWindow.location.pathname\n    const appMatch = pathname.match(/^\\/org\\/[^/]+\\/app\\/[^/]+/)\n    const orgMatch = pathname.match(/^\\/org\\/([^/]+)\\//)\n    return {\n      pathname,\n      orgId: orgMatch ? (orgMatch[1] ?? null) : null,\n      appBasePath: appMatch ? appMatch[0] : null,\n    }\n  } catch {\n    // Cross-origin (untrusted-component future) or detached — fall back to null.\n    return empty\n  }\n}\n\n/**\n * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`\n * prefix needed to build navigation targets on platform pages. Read once on\n * mount (the iframe re-inits when the host route changes).\n */\nexport function useHostLocation(): HostLocation {\n  const [loc] = useState(readHostLocation)\n  return loc\n}\n\nexport interface FillViewportOptions {\n  /** Gap left below the component (px). Default 24. */\n  bottomMargin?: number\n  /** Floor for the computed height (px). Default 320. */\n  minHeight?: number\n}\n\n/**\n * Compute a \"fill the rest of the viewport\" height for full-bleed layouts\n * (boards, canvases). The runtime auto-sizes the iframe to its content, so a\n * component can't use its own `vh` units (circular). The iframe is same-origin,\n * so this measures the parent viewport minus the iframe's offset instead.\n * Returns `null` when it can't measure (fall back to natural height).\n */\nexport function useFillViewportHeight(options: FillViewportOptions = {}): number | null {\n  const { bottomMargin = 24, minHeight = 320 } = options\n  const [height, setHeight] = useState<number | null>(null)\n\n  useEffect(() => {\n    function compute(): void {\n      try {\n        const frame = window.frameElement\n        const parentWindow = window.parent\n        if (!frame || !parentWindow || parentWindow === window) return\n        const available =\n          parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin\n        setHeight(Math.max(available, minHeight))\n      } catch {\n        setHeight(null) // cross-origin or detached — fall back to natural height\n      }\n    }\n    compute()\n    try {\n      window.parent.addEventListener('resize', compute)\n      return () => window.parent.removeEventListener('resize', compute)\n    } catch {\n      return\n    }\n  }, [bottomMargin, minHeight])\n\n  return height\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,134 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { AccountClient, AgentClient, DataClient, FunctionsClient, KnowledgeClient, MetaClient, StorageClient } from '@proteos/sdk';
+import { PageContext } from './protocol.cjs';
+export { AuthRefreshMessage, DataInvalidateMessage, Envelope, ErrorMessage, HostMessage, InitMessage, MESSAGE_SOURCE, NavigateMessage, OpenPeekMessage, ReadyMessage, ResizeMessage, RuntimeMessage, isHostMessage, isRuntimeMessage } from './protocol.cjs';
+
+/** Options for {@link RuntimeContextValue.navigate}. */
+interface NavigateOptions {
+    /** Open the target in a peek (slide-over) panel instead of full-page. */
+    peek?: boolean;
+}
+/**
+ * The authenticated `@proteos/sdk` clients the runtime injects. Same instances
+ * the host app uses — pre-wired with a refreshing bearer token, so a component
+ * never touches auth headers.
+ */
+interface ComponentSdk {
+    account: AccountClient;
+    agents: AgentClient;
+    data: DataClient;
+    functions: FunctionsClient;
+    knowledge: KnowledgeClient;
+    meta: MetaClient;
+    storage: StorageClient;
+}
+/**
+ * The raw runtime payload the shell hands a component at INIT. The shell builds
+ * this; component authors read it through the hooks.
+ */
+interface RuntimeValue {
+    sdk: ComponentSdk;
+    /** Liquid-resolved props (a snapshot — not a live binding). */
+    props: Record<string, unknown>;
+    /** Page context snapshot: the host record, entity, and URL params. */
+    pageCtx: PageContext;
+    /** API origin SDK calls + asset URLs resolve against. */
+    apiBaseUrl: string;
+    /** Current bearer token getter (escape hatch for raw fetches). */
+    getToken: () => string;
+}
+/** Runtime value plus the derived helpers the hooks expose. */
+interface RuntimeContextValue extends RuntimeValue {
+    /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or
+     *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */
+    navigate: (to: string, options?: NavigateOptions) => void;
+}
+/**
+ * Provides the runtime value + derived helpers to a component subtree. Mounted
+ * by the component-runtime shell around the loaded component — authors never
+ * render this themselves. Lives in `@proteos/component-sdk` (a shared,
+ * import-mapped singleton) so the context the shell provides is the very same
+ * context the component's hooks read, across the bundle boundary.
+ */
+declare function RuntimeProvider({ value, children }: {
+    value: RuntimeValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare global {
+    interface Window {
+        __PROTEOS_RUNTIME__?: {
+            apiBaseUrl: string;
+            getToken: () => string;
+            props: Record<string, unknown>;
+            pageCtx: PageContext;
+            sdk: ComponentSdk;
+        };
+    }
+}
+
+/**
+ * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,
+ * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a
+ * clear error if used outside the component runtime.
+ */
+declare function useRuntime(): RuntimeContextValue;
+/** The authenticated SDK clients (account / data / functions / meta). */
+declare function useSdk(): ComponentSdk;
+/** The component's Liquid-resolved props (a snapshot, not a live binding). */
+declare function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+/**
+ * The full page context: host `record`, `entity`, and URL `params`. The
+ * `record` is a snapshot taken at mount (`undefined` on record-less platform
+ * pages) — fetch via `useSdk().data` for anything that must stay fresh.
+ */
+declare function usePageContext(): PageContext;
+/**
+ * Navigate the host SPA to an in-app path, e.g.
+ * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external
+ * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.
+ *
+ * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead
+ * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host
+ * peeks what it can (today: platform pages) and falls back to full navigation.
+ */
+declare function useNavigate(): (to: string, options?: NavigateOptions) => void;
+/** The API origin SDK calls resolve against (for building raw asset URLs). */
+declare function useApiBaseUrl(): string;
+/**
+ * A getter for the current bearer token. Returns a function (not the token)
+ * because the token is refreshed in place — read it at call time for a raw
+ * `fetch`. Most components never need this; prefer `useSdk()`.
+ */
+declare function useAuthToken(): () => string;
+interface HostLocation {
+    /** The host tab's pathname (same-origin read), or null if unavailable. */
+    pathname: string | null;
+    /** The org id parsed from `/org/<orgId>/…`, or null. */
+    orgId: string | null;
+    /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */
+    appBasePath: string | null;
+}
+/**
+ * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`
+ * prefix needed to build navigation targets on platform pages. Read once on
+ * mount (the iframe re-inits when the host route changes).
+ */
+declare function useHostLocation(): HostLocation;
+interface FillViewportOptions {
+    /** Gap left below the component (px). Default 24. */
+    bottomMargin?: number;
+    /** Floor for the computed height (px). Default 320. */
+    minHeight?: number;
+}
+/**
+ * Compute a "fill the rest of the viewport" height for full-bleed layouts
+ * (boards, canvases). The runtime auto-sizes the iframe to its content, so a
+ * component can't use its own `vh` units (circular). The iframe is same-origin,
+ * so this measures the parent viewport minus the iframe's offset instead.
+ * Returns `null` when it can't measure (fall back to natural height).
+ */
+declare function useFillViewportHeight(options?: FillViewportOptions): number | null;
+
+export { type ComponentSdk, type FillViewportOptions, type HostLocation, type NavigateOptions, PageContext, type RuntimeContextValue, RuntimeProvider, type RuntimeValue, useApiBaseUrl, useAuthToken, useFillViewportHeight, useHostLocation, useNavigate, usePageContext, useProps, useRuntime, useSdk };

package/dist/index.d.ts

@@ -0,0 +1,134 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { AccountClient, AgentClient, DataClient, FunctionsClient, KnowledgeClient, MetaClient, StorageClient } from '@proteos/sdk';
+import { PageContext } from './protocol.js';
+export { AuthRefreshMessage, DataInvalidateMessage, Envelope, ErrorMessage, HostMessage, InitMessage, MESSAGE_SOURCE, NavigateMessage, OpenPeekMessage, ReadyMessage, ResizeMessage, RuntimeMessage, isHostMessage, isRuntimeMessage } from './protocol.js';
+
+/** Options for {@link RuntimeContextValue.navigate}. */
+interface NavigateOptions {
+    /** Open the target in a peek (slide-over) panel instead of full-page. */
+    peek?: boolean;
+}
+/**
+ * The authenticated `@proteos/sdk` clients the runtime injects. Same instances
+ * the host app uses — pre-wired with a refreshing bearer token, so a component
+ * never touches auth headers.
+ */
+interface ComponentSdk {
+    account: AccountClient;
+    agents: AgentClient;
+    data: DataClient;
+    functions: FunctionsClient;
+    knowledge: KnowledgeClient;
+    meta: MetaClient;
+    storage: StorageClient;
+}
+/**
+ * The raw runtime payload the shell hands a component at INIT. The shell builds
+ * this; component authors read it through the hooks.
+ */
+interface RuntimeValue {
+    sdk: ComponentSdk;
+    /** Liquid-resolved props (a snapshot — not a live binding). */
+    props: Record<string, unknown>;
+    /** Page context snapshot: the host record, entity, and URL params. */
+    pageCtx: PageContext;
+    /** API origin SDK calls + asset URLs resolve against. */
+    apiBaseUrl: string;
+    /** Current bearer token getter (escape hatch for raw fetches). */
+    getToken: () => string;
+}
+/** Runtime value plus the derived helpers the hooks expose. */
+interface RuntimeContextValue extends RuntimeValue {
+    /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or
+     *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */
+    navigate: (to: string, options?: NavigateOptions) => void;
+}
+/**
+ * Provides the runtime value + derived helpers to a component subtree. Mounted
+ * by the component-runtime shell around the loaded component — authors never
+ * render this themselves. Lives in `@proteos/component-sdk` (a shared,
+ * import-mapped singleton) so the context the shell provides is the very same
+ * context the component's hooks read, across the bundle boundary.
+ */
+declare function RuntimeProvider({ value, children }: {
+    value: RuntimeValue;
+    children: ReactNode;
+}): react_jsx_runtime.JSX.Element;
+
+declare global {
+    interface Window {
+        __PROTEOS_RUNTIME__?: {
+            apiBaseUrl: string;
+            getToken: () => string;
+            props: Record<string, unknown>;
+            pageCtx: PageContext;
+            sdk: ComponentSdk;
+        };
+    }
+}
+
+/**
+ * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,
+ * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a
+ * clear error if used outside the component runtime.
+ */
+declare function useRuntime(): RuntimeContextValue;
+/** The authenticated SDK clients (account / data / functions / meta). */
+declare function useSdk(): ComponentSdk;
+/** The component's Liquid-resolved props (a snapshot, not a live binding). */
+declare function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+/**
+ * The full page context: host `record`, `entity`, and URL `params`. The
+ * `record` is a snapshot taken at mount (`undefined` on record-less platform
+ * pages) — fetch via `useSdk().data` for anything that must stay fresh.
+ */
+declare function usePageContext(): PageContext;
+/**
+ * Navigate the host SPA to an in-app path, e.g.
+ * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external
+ * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.
+ *
+ * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead
+ * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host
+ * peeks what it can (today: platform pages) and falls back to full navigation.
+ */
+declare function useNavigate(): (to: string, options?: NavigateOptions) => void;
+/** The API origin SDK calls resolve against (for building raw asset URLs). */
+declare function useApiBaseUrl(): string;
+/**
+ * A getter for the current bearer token. Returns a function (not the token)
+ * because the token is refreshed in place — read it at call time for a raw
+ * `fetch`. Most components never need this; prefer `useSdk()`.
+ */
+declare function useAuthToken(): () => string;
+interface HostLocation {
+    /** The host tab's pathname (same-origin read), or null if unavailable. */
+    pathname: string | null;
+    /** The org id parsed from `/org/<orgId>/…`, or null. */
+    orgId: string | null;
+    /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */
+    appBasePath: string | null;
+}
+/**
+ * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`
+ * prefix needed to build navigation targets on platform pages. Read once on
+ * mount (the iframe re-inits when the host route changes).
+ */
+declare function useHostLocation(): HostLocation;
+interface FillViewportOptions {
+    /** Gap left below the component (px). Default 24. */
+    bottomMargin?: number;
+    /** Floor for the computed height (px). Default 320. */
+    minHeight?: number;
+}
+/**
+ * Compute a "fill the rest of the viewport" height for full-bleed layouts
+ * (boards, canvases). The runtime auto-sizes the iframe to its content, so a
+ * component can't use its own `vh` units (circular). The iframe is same-origin,
+ * so this measures the parent viewport minus the iframe's offset instead.
+ * Returns `null` when it can't measure (fall back to natural height).
+ */
+declare function useFillViewportHeight(options?: FillViewportOptions): number | null;
+
+export { type ComponentSdk, type FillViewportOptions, type HostLocation, type NavigateOptions, PageContext, type RuntimeContextValue, RuntimeProvider, type RuntimeValue, useApiBaseUrl, useAuthToken, useFillViewportHeight, useHostLocation, useNavigate, usePageContext, useProps, useRuntime, useSdk };

package/dist/index.js

@@ -0,0 +1,99 @@
+import { MESSAGE_SOURCE } from './chunk-NMXHDDL6.js';
+export { MESSAGE_SOURCE, isHostMessage, isRuntimeMessage } from './chunk-NMXHDDL6.js';
+import { createContext, useMemo, useContext, useState, useEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var RuntimeContext = createContext(null);
+function postNavigate(to) {
+  const envelope = { source: MESSAGE_SOURCE, type: "NAVIGATE", to };
+  window.parent?.postMessage(envelope, "*");
+}
+function postOpenPeek(to) {
+  const envelope = { source: MESSAGE_SOURCE, type: "OPEN_PEEK", to };
+  window.parent?.postMessage(envelope, "*");
+}
+function navigate(to, options) {
+  if (options?.peek) postOpenPeek(to);
+  else postNavigate(to);
+}
+function RuntimeProvider({ value, children }) {
+  const ctx = useMemo(() => ({ ...value, navigate }), [value]);
+  return /* @__PURE__ */ jsx(RuntimeContext.Provider, { value: ctx, children });
+}
+function useRuntime() {
+  const ctx = useContext(RuntimeContext);
+  if (!ctx) {
+    throw new Error(
+      "@proteos/component-sdk: hooks must run inside the Proteos component runtime. This usually means the component is rendered outside its iframe, or a second copy of @proteos/component-sdk was bundled instead of using the runtime-provided one (keep it external)."
+    );
+  }
+  return ctx;
+}
+function useSdk() {
+  return useRuntime().sdk;
+}
+function useProps() {
+  return useRuntime().props;
+}
+function usePageContext() {
+  return useRuntime().pageCtx;
+}
+function useNavigate() {
+  return useRuntime().navigate;
+}
+function useApiBaseUrl() {
+  return useRuntime().apiBaseUrl;
+}
+function useAuthToken() {
+  return useRuntime().getToken;
+}
+function readHostLocation() {
+  const empty = { pathname: null, orgId: null, appBasePath: null };
+  try {
+    const parentWindow = window.parent;
+    if (!parentWindow || parentWindow === window) return empty;
+    const pathname = parentWindow.location.pathname;
+    const appMatch = pathname.match(/^\/org\/[^/]+\/app\/[^/]+/);
+    const orgMatch = pathname.match(/^\/org\/([^/]+)\//);
+    return {
+      pathname,
+      orgId: orgMatch ? orgMatch[1] ?? null : null,
+      appBasePath: appMatch ? appMatch[0] : null
+    };
+  } catch {
+    return empty;
+  }
+}
+function useHostLocation() {
+  const [loc] = useState(readHostLocation);
+  return loc;
+}
+function useFillViewportHeight(options = {}) {
+  const { bottomMargin = 24, minHeight = 320 } = options;
+  const [height, setHeight] = useState(null);
+  useEffect(() => {
+    function compute() {
+      try {
+        const frame = window.frameElement;
+        const parentWindow = window.parent;
+        if (!frame || !parentWindow || parentWindow === window) return;
+        const available = parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin;
+        setHeight(Math.max(available, minHeight));
+      } catch {
+        setHeight(null);
+      }
+    }
+    compute();
+    try {
+      window.parent.addEventListener("resize", compute);
+      return () => window.parent.removeEventListener("resize", compute);
+    } catch {
+      return;
+    }
+  }, [bottomMargin, minHeight]);
+  return height;
+}
+
+export { RuntimeProvider, useApiBaseUrl, useAuthToken, useFillViewportHeight, useHostLocation, useNavigate, usePageContext, useProps, useRuntime, useSdk };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/context.tsx","../src/hooks.ts"],"names":[],"mappings":";;;;;AA+DO,IAAM,cAAA,GAAiB,cAA0C,IAAI,CAAA;AAI5E,SAAS,aAAa,EAAA,EAAkB;AACtC,EAAA,MAAM,WAAsC,EAAE,MAAA,EAAQ,cAAA,EAAgB,IAAA,EAAM,YAAY,EAAA,EAAG;AAC3F,EAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAC1C;AAIA,SAAS,aAAa,EAAA,EAAkB;AACtC,EAAA,MAAM,WAAsC,EAAE,MAAA,EAAQ,cAAA,EAAgB,IAAA,EAAM,aAAa,EAAA,EAAG;AAC5F,EAAA,MAAA,CAAO,MAAA,EAAQ,WAAA,CAAY,QAAA,EAAU,GAAG,CAAA;AAC1C;AAGA,SAAS,QAAA,CAAS,IAAY,OAAA,EAAiC;AAC7D,EAAA,IAAI,OAAA,EAAS,IAAA,EAAM,YAAA,CAAa,EAAE,CAAA;AAAA,oBAChB,EAAE,CAAA;AACtB;AASO,SAAS,eAAA,CAAgB,EAAE,KAAA,EAAO,QAAA,EAAS,EAAiD;AAIjG,EAAA,MAAM,GAAA,GAAM,OAAA,CAA6B,OAAO,EAAE,GAAG,OAAO,QAAA,EAAS,CAAA,EAAI,CAAC,KAAK,CAAC,CAAA;AAChF,EAAA,2BAAQ,cAAA,CAAe,QAAA,EAAf,EAAwB,KAAA,EAAO,KAAM,QAAA,EAAS,CAAA;AACxD;ACnFO,SAAS,UAAA,GAAkC;AAChD,EAAA,MAAM,GAAA,GAAM,WAAW,cAAc,CAAA;AACrC,EAAA,IAAI,CAAC,GAAA,EAAK;AACR,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KAIF;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,MAAA,GAAuB;AACrC,EAAA,OAAO,YAAW,CAAE,GAAA;AACtB;AAGO,SAAS,QAAA,GAA2E;AACzF,EAAA,OAAO,YAAW,CAAE,KAAA;AACtB;AAOO,SAAS,cAAA,GAA8B;AAC5C,EAAA,OAAO,YAAW,CAAE,OAAA;AACtB;AAWO,SAAS,WAAA,GAA+D;AAC7E,EAAA,OAAO,YAAW,CAAE,QAAA;AACtB;AAGO,SAAS,aAAA,GAAwB;AACtC,EAAA,OAAO,YAAW,CAAE,UAAA;AACtB;AAOO,SAAS,YAAA,GAA6B;AAC3C,EAAA,OAAO,YAAW,CAAE,QAAA;AACtB;AAWA,SAAS,gBAAA,GAAiC;AACxC,EAAA,MAAM,QAAsB,EAAE,QAAA,EAAU,MAAM,KAAA,EAAO,IAAA,EAAM,aAAa,IAAA,EAAK;AAC7E,EAAA,IAAI;AACF,IAAA,MAAM,eAAe,MAAA,CAAO,MAAA;AAC5B,IAAA,IAAI,CAAC,YAAA,IAAgB,YAAA,KAAiB,MAAA,EAAQ,OAAO,KAAA;AACrD,IAAA,MAAM,QAAA,GAAW,aAAa,QAAA,CAAS,QAAA;AACvC,IAAA,MAAM,QAAA,GAAW,QAAA,CAAS,KAAA,CAAM,2BAA2B,CAAA;AAC3D,IAAA,MAAM,QAAA,GAAW,QAAA,CAAS,KAAA,CAAM,mBAAmB,CAAA;AACnD,IAAA,OAAO;AAAA,MACL,QAAA;AAAA,MACA,KAAA,EAAO,QAAA,GAAY,QAAA,CAAS,CAAC,KAAK,IAAA,GAAQ,IAAA;AAAA,MAC1C,WAAA,EAAa,QAAA,GAAW,QAAA,CAAS,CAAC,CAAA,GAAI;AAAA,KACxC;AAAA,EACF,CAAA,CAAA,MAAQ;AAEN,IAAA,OAAO,KAAA;AAAA,EACT;AACF;AAOO,SAAS,eAAA,GAAgC;AAC9C,EAAA,MAAM,CAAC,GAAG,CAAA,GAAI,QAAA,CAAS,gBAAgB,CAAA;AACvC,EAAA,OAAO,GAAA;AACT;AAgBO,SAAS,qBAAA,CAAsB,OAAA,GAA+B,EAAC,EAAkB;AACtF,EAAA,MAAM,EAAE,YAAA,GAAe,EAAA,EAAI,SAAA,GAAY,KAAI,GAAI,OAAA;AAC/C,EAAA,MAAM,CAAC,MAAA,EAAQ,SAAS,CAAA,GAAI,SAAwB,IAAI,CAAA;AAExD,EAAA,SAAA,CAAU,MAAM;AACd,IAAA,SAAS,OAAA,GAAgB;AACvB,MAAA,IAAI;AACF,QAAA,MAAM,QAAQ,MAAA,CAAO,YAAA;AACrB,QAAA,MAAM,eAAe,MAAA,CAAO,MAAA;AAC5B,QAAA,IAAI,CAAC,KAAA,IAAS,CAAC,YAAA,IAAgB,iBAAiB,MAAA,EAAQ;AACxD,QAAA,MAAM,YACJ,YAAA,CAAa,WAAA,GAAc,KAAA,CAAM,qBAAA,GAAwB,GAAA,GAAM,YAAA;AACjE,QAAA,SAAA,CAAU,IAAA,CAAK,GAAA,CAAI,SAAA,EAAW,SAAS,CAAC,CAAA;AAAA,MAC1C,CAAA,CAAA,MAAQ;AACN,QAAA,SAAA,CAAU,IAAI,CAAA;AAAA,MAChB;AAAA,IACF;AACA,IAAA,OAAA,EAAQ;AACR,IAAA,IAAI;AACF,MAAA,MAAA,CAAO,MAAA,CAAO,gBAAA,CAAiB,QAAA,EAAU,OAAO,CAAA;AAChD,MAAA,OAAO,MAAM,MAAA,CAAO,MAAA,CAAO,mBAAA,CAAoB,UAAU,OAAO,CAAA;AAAA,IAClE,CAAA,CAAA,MAAQ;AACN,MAAA;AAAA,IACF;AAAA,EACF,CAAA,EAAG,CAAC,YAAA,EAAc,SAAS,CAAC,CAAA;AAE5B,EAAA,OAAO,MAAA;AACT","file":"index.js","sourcesContent":["import type {\n  AccountClient,\n  AgentClient,\n  DataClient,\n  FunctionsClient,\n  KnowledgeClient,\n  MetaClient,\n  StorageClient,\n} from '@proteos/sdk'\nimport { createContext, type ReactNode, useMemo } from 'react'\n\nimport {\n  type Envelope,\n  MESSAGE_SOURCE,\n  type NavigateMessage,\n  type OpenPeekMessage,\n  type PageContext,\n} from './protocol'\n\n/** Options for {@link RuntimeContextValue.navigate}. */\nexport interface NavigateOptions {\n  /** Open the target in a peek (slide-over) panel instead of full-page. */\n  peek?: boolean\n}\n\n/**\n * The authenticated `@proteos/sdk` clients the runtime injects. Same instances\n * the host app uses — pre-wired with a refreshing bearer token, so a component\n * never touches auth headers.\n */\nexport interface ComponentSdk {\n  account: AccountClient\n  agents: AgentClient\n  data: DataClient\n  functions: FunctionsClient\n  knowledge: KnowledgeClient\n  meta: MetaClient\n  storage: StorageClient\n}\n\n/**\n * The raw runtime payload the shell hands a component at INIT. The shell builds\n * this; component authors read it through the hooks.\n */\nexport interface RuntimeValue {\n  sdk: ComponentSdk\n  /** Liquid-resolved props (a snapshot — not a live binding). */\n  props: Record<string, unknown>\n  /** Page context snapshot: the host record, entity, and URL params. */\n  pageCtx: PageContext\n  /** API origin SDK calls + asset URLs resolve against. */\n  apiBaseUrl: string\n  /** Current bearer token getter (escape hatch for raw fetches). */\n  getToken: () => string\n}\n\n/** Runtime value plus the derived helpers the hooks expose. */\nexport interface RuntimeContextValue extends RuntimeValue {\n  /** Navigate the host SPA to an in-app path (posts a NAVIGATE message), or\n   *  open it in a peek panel with `{ peek: true }` (posts OPEN_PEEK). */\n  navigate: (to: string, options?: NavigateOptions) => void\n}\n\nexport const RuntimeContext = createContext<RuntimeContextValue | null>(null)\n\n/** Post a NAVIGATE envelope to the host. The host only honours relative,\n *  in-app targets (it ignores absolute/external URLs). */\nfunction postNavigate(to: string): void {\n  const envelope: Envelope<NavigateMessage> = { source: MESSAGE_SOURCE, type: 'NAVIGATE', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Post an OPEN_PEEK envelope to the host — open the in-app path in a peek\n *  panel. Same relative-path contract as {@link postNavigate}. */\nfunction postOpenPeek(to: string): void {\n  const envelope: Envelope<OpenPeekMessage> = { source: MESSAGE_SOURCE, type: 'OPEN_PEEK', to }\n  window.parent?.postMessage(envelope, '*')\n}\n\n/** Navigate full-page (default) or into a peek panel (`{ peek: true }`). */\nfunction navigate(to: string, options?: NavigateOptions): void {\n  if (options?.peek) postOpenPeek(to)\n  else postNavigate(to)\n}\n\n/**\n * Provides the runtime value + derived helpers to a component subtree. Mounted\n * by the component-runtime shell around the loaded component — authors never\n * render this themselves. Lives in `@proteos/component-sdk` (a shared,\n * import-mapped singleton) so the context the shell provides is the very same\n * context the component's hooks read, across the bundle boundary.\n */\nexport function RuntimeProvider({ value, children }: { value: RuntimeValue; children: ReactNode }) {\n  // The shell builds `value` once at INIT (a stable state object — clients,\n  // props and pageCtx are all set once), so memoizing on its identity recreates\n  // the context only when the runtime genuinely re-inits.\n  const ctx = useMemo<RuntimeContextValue>(() => ({ ...value, navigate }), [value])\n  return <RuntimeContext.Provider value={ctx}>{children}</RuntimeContext.Provider>\n}\n","import { useContext, useEffect, useState } from 'react'\n\nimport {\n  type ComponentSdk,\n  type NavigateOptions,\n  RuntimeContext,\n  type RuntimeContextValue,\n} from './context'\nimport type { PageContext } from './protocol'\n\n/**\n * Low-level escape hatch: the whole runtime context (sdk, props, pageCtx,\n * apiBaseUrl, getToken, navigate). Prefer the focused hooks below. Throws a\n * clear error if used outside the component runtime.\n */\nexport function useRuntime(): RuntimeContextValue {\n  const ctx = useContext(RuntimeContext)\n  if (!ctx) {\n    throw new Error(\n      '@proteos/component-sdk: hooks must run inside the Proteos component runtime. ' +\n        'This usually means the component is rendered outside its iframe, or a ' +\n        'second copy of @proteos/component-sdk was bundled instead of using the ' +\n        'runtime-provided one (keep it external).',\n    )\n  }\n  return ctx\n}\n\n/** The authenticated SDK clients (account / data / functions / meta). */\nexport function useSdk(): ComponentSdk {\n  return useRuntime().sdk\n}\n\n/** The component's Liquid-resolved props (a snapshot, not a live binding). */\nexport function useProps<T extends Record<string, unknown> = Record<string, unknown>>(): T {\n  return useRuntime().props as T\n}\n\n/**\n * The full page context: host `record`, `entity`, and URL `params`. The\n * `record` is a snapshot taken at mount (`undefined` on record-less platform\n * pages) — fetch via `useSdk().data` for anything that must stay fresh.\n */\nexport function usePageContext(): PageContext {\n  return useRuntime().pageCtx\n}\n\n/**\n * Navigate the host SPA to an in-app path, e.g.\n * `navigate('/org/acme/record/task/123')`. The host ignores absolute/external\n * URLs. Build org/app-prefixed paths with `useHostLocation().appBasePath`.\n *\n * Pass `{ peek: true }` to open the path in a peek (slide-over) panel instead\n * of full-page navigation — e.g. `navigate(path, { peek: true })`. The host\n * peeks what it can (today: platform pages) and falls back to full navigation.\n */\nexport function useNavigate(): (to: string, options?: NavigateOptions) => void {\n  return useRuntime().navigate\n}\n\n/** The API origin SDK calls resolve against (for building raw asset URLs). */\nexport function useApiBaseUrl(): string {\n  return useRuntime().apiBaseUrl\n}\n\n/**\n * A getter for the current bearer token. Returns a function (not the token)\n * because the token is refreshed in place — read it at call time for a raw\n * `fetch`. Most components never need this; prefer `useSdk()`.\n */\nexport function useAuthToken(): () => string {\n  return useRuntime().getToken\n}\n\nexport interface HostLocation {\n  /** The host tab's pathname (same-origin read), or null if unavailable. */\n  pathname: string | null\n  /** The org id parsed from `/org/<orgId>/…`, or null. */\n  orgId: string | null\n  /** The `/org/<orgId>/app/<appId>` prefix, or null when not on an app page. */\n  appBasePath: string | null\n}\n\nfunction readHostLocation(): HostLocation {\n  const empty: HostLocation = { pathname: null, orgId: null, appBasePath: null }\n  try {\n    const parentWindow = window.parent\n    if (!parentWindow || parentWindow === window) return empty\n    const pathname = parentWindow.location.pathname\n    const appMatch = pathname.match(/^\\/org\\/[^/]+\\/app\\/[^/]+/)\n    const orgMatch = pathname.match(/^\\/org\\/([^/]+)\\//)\n    return {\n      pathname,\n      orgId: orgMatch ? (orgMatch[1] ?? null) : null,\n      appBasePath: appMatch ? appMatch[0] : null,\n    }\n  } catch {\n    // Cross-origin (untrusted-component future) or detached — fall back to null.\n    return empty\n  }\n}\n\n/**\n * Read the host tab's location (same-origin) — the org id and `/org/.../app/...`\n * prefix needed to build navigation targets on platform pages. Read once on\n * mount (the iframe re-inits when the host route changes).\n */\nexport function useHostLocation(): HostLocation {\n  const [loc] = useState(readHostLocation)\n  return loc\n}\n\nexport interface FillViewportOptions {\n  /** Gap left below the component (px). Default 24. */\n  bottomMargin?: number\n  /** Floor for the computed height (px). Default 320. */\n  minHeight?: number\n}\n\n/**\n * Compute a \"fill the rest of the viewport\" height for full-bleed layouts\n * (boards, canvases). The runtime auto-sizes the iframe to its content, so a\n * component can't use its own `vh` units (circular). The iframe is same-origin,\n * so this measures the parent viewport minus the iframe's offset instead.\n * Returns `null` when it can't measure (fall back to natural height).\n */\nexport function useFillViewportHeight(options: FillViewportOptions = {}): number | null {\n  const { bottomMargin = 24, minHeight = 320 } = options\n  const [height, setHeight] = useState<number | null>(null)\n\n  useEffect(() => {\n    function compute(): void {\n      try {\n        const frame = window.frameElement\n        const parentWindow = window.parent\n        if (!frame || !parentWindow || parentWindow === window) return\n        const available =\n          parentWindow.innerHeight - frame.getBoundingClientRect().top - bottomMargin\n        setHeight(Math.max(available, minHeight))\n      } catch {\n        setHeight(null) // cross-origin or detached — fall back to natural height\n      }\n    }\n    compute()\n    try {\n      window.parent.addEventListener('resize', compute)\n      return () => window.parent.removeEventListener('resize', compute)\n    } catch {\n      return\n    }\n  }, [bottomMargin, minHeight])\n\n  return height\n}\n"]}