@asteby/metacore-runtime-react 9.1.0 → 10.0.0

package/dist/manifest-hotswap-subscriber.d.ts

@@ -0,0 +1,83 @@
+import { type AddonKeyMatcher } from './metadata-cache';
+/**
+ * `type` string the kernel/bridge emits. Exported so consumers can subscribe
+ * manually if they prefer to skip the hook/wire helper. Matches
+ * `bridge.WSManifestChangedType` in metacore-kernel.
+ */
+export declare const ADDON_MANIFEST_CHANGED_TYPE: "ADDON_MANIFEST_CHANGED";
+/**
+ * Shape of the WebSocket message the kernel emits. The keys mirror the
+ * `bridge.manifestChangedPayload` map in metacore-kernel/bridge — keep them
+ * in sync if the bridge ever evolves.
+ */
+export interface AddonManifestChangedMessage {
+    type: typeof ADDON_MANIFEST_CHANGED_TYPE;
+    payload: {
+        orgId?: string;
+        addonKey: string;
+        oldHash?: string;
+        newHash?: string;
+        version?: string;
+        timestamp?: string;
+    };
+}
+/**
+ * Structural client contract. The SDK's `@asteby/metacore-websocket`
+ * provider exposes `subscribe(type, handler)` (see `useWebSocket().subscribe`)
+ * that satisfies this interface — but any object with a compatible method
+ * works, so hosts that wrap their own transport (link's MQTT bridge, the
+ * kitchen-display ZeroMQ stub, …) can plug in without depending on the
+ * SDK websocket package.
+ */
+export interface ManifestHotSwapClient {
+    subscribe: (type: string, handler: (message: AddonManifestChangedMessage) => void) => () => void;
+}
+export interface WireHotSwapInvalidationOptions {
+    /**
+     * Optional matcher overriding the default cache-key heuristic
+     * (see `defaultAddonKeyMatcher`). Hosts that namespace cached
+     * `model` keys under prefixes other than `${addonKey}.|:|/` should
+     * supply one.
+     */
+    matcher?: AddonKeyMatcher;
+    /**
+     * Optional side-effect hook invoked after the cache invalidation.
+     * Useful for hosts that want to log/observe hot-swaps or trigger a
+     * `window.location.reload()` when the running addon's bundle hash
+     * changes (see the module-level comment above for the trade-off).
+     * `removed` is the number of cache entries flushed for this addon.
+     */
+    onSwap?: (msg: AddonManifestChangedMessage, removed: number) => void;
+}
+/**
+ * Imperative wire-up — no React required. Hosts that own a long-lived
+ * WebSocket client (link, ops, the kitchen-display Tauri shell) call this
+ * once at boot, after the client has been created. The returned function
+ * unsubscribes; most hosts will never call it because the subscription
+ * lives for the lifetime of the app.
+ *
+ *   const ws = createWebSocket(...)
+ *   const unsubscribe = wireHotSwapInvalidation(ws)
+ *   // …later, if needed:
+ *   unsubscribe()
+ *
+ * Accepts `undefined` so the call site does not need to branch when the
+ * client is constructed lazily — it returns a no-op unsubscribe.
+ */
+export declare function wireHotSwapInvalidation(client: ManifestHotSwapClient | undefined | null, options?: WireHotSwapInvalidationOptions): () => void;
+/**
+ * React-flavoured wrapper around {@link wireHotSwapInvalidation}. Mount it
+ * once high in the tree (typically next to the WebSocket provider) so the
+ * subscription lifetime matches the host shell. Passing `undefined` for
+ * the client is supported — the hook becomes a no-op until a real client
+ * is available, mirroring how `useWebSocket().subscribe` behaves before
+ * the socket opens.
+ *
+ *   function HostShell() {
+ *     const ws = useWebSocket()
+ *     useManifestHotSwapSubscriber(ws)
+ *     return <Outlet />
+ *   }
+ */
+export declare function useManifestHotSwapSubscriber(client: ManifestHotSwapClient | undefined | null, options?: WireHotSwapInvalidationOptions): void;
+//# sourceMappingURL=manifest-hotswap-subscriber.d.ts.map

package/dist/manifest-hotswap-subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-hotswap-subscriber.d.ts","sourceRoot":"","sources":["../src/manifest-hotswap-subscriber.ts"],"names":[],"mappings":"AA6CA,OAAO,EAAoB,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEzE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAG,wBAAiC,CAAA;AAE5E;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IACxC,IAAI,EAAE,OAAO,2BAA2B,CAAA;IACxC,OAAO,EAAE;QACL,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,SAAS,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;CACJ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,CACP,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,IAAI,KACtD,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,8BAA8B;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,2BAA2B,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACvE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,EAChD,OAAO,GAAE,8BAAmC,GAC7C,MAAM,IAAI,CAeZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,4BAA4B,CACxC,MAAM,EAAE,qBAAqB,GAAG,SAAS,GAAG,IAAI,EAChD,OAAO,GAAE,8BAAmC,GAC7C,IAAI,CAON"}

package/dist/manifest-hotswap-subscriber.js

@@ -0,0 +1,104 @@
+// manifest-hotswap-subscriber — client-side closure of RFC-0001 D4.
+//
+// The kernel installer (see metacore-kernel/installer/broadcaster.go) emits a
+// WebSocket message every time it observes a manifest-hash change at persist
+// time. The bridge (metacore-kernel/bridge/installer_broadcaster.go) fans it
+// out per-org over `ws.Hub.SendToUsers` with this exact envelope:
+//
+//   {
+//     "type": "ADDON_MANIFEST_CHANGED",
+//     "payload": {
+//       "orgId": "<uuid>",
+//       "addonKey": "kitchen_display",
+//       "oldHash": "sha256:...",
+//       "newHash": "sha256:...",
+//       "version": "1.2.0",
+//       "timestamp": "2026-05-11T12:34:56Z"
+//     }
+//   }
+//
+// (The original RFC scratchpad used snake_case keys; the bridge canonicalised
+// them to camelCase so the SDK's metadata-cache reducer can consume the
+// payload verbatim. This module matches the bridge — the source of truth.)
+//
+// This module wires the message into `useMetadataCache().invalidateAddon` so
+// every cached table/modal metadata entry belonging to the bumped addon is
+// dropped from the zustand store. The next mount of any `DynamicTable` or
+// `DynamicCRUDPage` will refetch fresh metadata, picking up whatever the
+// new manifest changed (new fields, renamed actions, dropped relations…).
+//
+// IMPORTANT — a freshly-bumped addon whose `remoteEntry.js` URL changes will
+// also need its federation container reloaded. Cache invalidation handles
+// metadata; it does NOT swap the JS already executing in memory. If your
+// host wants the new code to take effect immediately, either:
+//
+//   1. force a full `window.location.reload()` when an `addon:manifest:changed`
+//      event arrives for the addon currently mounted, or
+//   2. for immersive addons (`layout: "immersive"`) where users tolerate a
+//      flicker, key the addon route component on `newHash` so React unmounts
+//      and remounts the AddonLoader with the new remoteEntry URL.
+//
+// The subscriber here intentionally stops at metadata-cache: deciding when
+// to reload is a host policy decision and we keep this module side-effect
+// free beyond the cache.
+import { useEffect } from 'react';
+import { useMetadataCache } from './metadata-cache';
+/**
+ * `type` string the kernel/bridge emits. Exported so consumers can subscribe
+ * manually if they prefer to skip the hook/wire helper. Matches
+ * `bridge.WSManifestChangedType` in metacore-kernel.
+ */
+export const ADDON_MANIFEST_CHANGED_TYPE = 'ADDON_MANIFEST_CHANGED';
+/**
+ * Imperative wire-up — no React required. Hosts that own a long-lived
+ * WebSocket client (link, ops, the kitchen-display Tauri shell) call this
+ * once at boot, after the client has been created. The returned function
+ * unsubscribes; most hosts will never call it because the subscription
+ * lives for the lifetime of the app.
+ *
+ *   const ws = createWebSocket(...)
+ *   const unsubscribe = wireHotSwapInvalidation(ws)
+ *   // …later, if needed:
+ *   unsubscribe()
+ *
+ * Accepts `undefined` so the call site does not need to branch when the
+ * client is constructed lazily — it returns a no-op unsubscribe.
+ */
+export function wireHotSwapInvalidation(client, options = {}) {
+    if (!client)
+        return () => { };
+    const { matcher, onSwap } = options;
+    const unsubscribe = client.subscribe(ADDON_MANIFEST_CHANGED_TYPE, (message) => {
+        const addonKey = message?.payload?.addonKey;
+        if (!addonKey)
+            return;
+        const removed = useMetadataCache
+            .getState()
+            .invalidateAddon(addonKey, matcher);
+        onSwap?.(message, removed);
+    });
+    return unsubscribe;
+}
+/**
+ * React-flavoured wrapper around {@link wireHotSwapInvalidation}. Mount it
+ * once high in the tree (typically next to the WebSocket provider) so the
+ * subscription lifetime matches the host shell. Passing `undefined` for
+ * the client is supported — the hook becomes a no-op until a real client
+ * is available, mirroring how `useWebSocket().subscribe` behaves before
+ * the socket opens.
+ *
+ *   function HostShell() {
+ *     const ws = useWebSocket()
+ *     useManifestHotSwapSubscriber(ws)
+ *     return <Outlet />
+ *   }
+ */
+export function useManifestHotSwapSubscriber(client, options = {}) {
+    const { matcher, onSwap } = options;
+    useEffect(() => {
+        if (!client)
+            return;
+        const unsubscribe = wireHotSwapInvalidation(client, { matcher, onSwap });
+        return unsubscribe;
+    }, [client, matcher, onSwap]);
+}

package/dist/metadata-cache.d.ts

@@ -4,6 +4,21 @@ export interface MetadataApiClient {
         data: any;
     }>;
 }
+/**
+ * Predicate matching a cache key against an addon. The default
+ * implementation (see {@link defaultAddonKeyMatcher}) treats `addonKey`
+ * itself plus any key beginning with `${addonKey}.`, `${addonKey}:` or
+ * `${addonKey}/` as belonging to the addon. Hosts that namespace their
+ * `model` strings differently can pass a custom matcher to
+ * {@link MetadataCacheState.invalidateAddon}.
+ */
+export type AddonKeyMatcher = (cacheKey: string, addonKey: string) => boolean;
+/**
+ * Default matcher used by {@link MetadataCacheState.invalidateAddon}.
+ * Mirrors the convention used by the kernel installer when it scopes
+ * model metadata under an addon's key.
+ */
+export declare function defaultAddonKeyMatcher(cacheKey: string, addonKey: string): boolean;
 interface MetadataCacheState {
     cache: Record<string, TableMetadata>;
     modalCache: Record<string, TableMetadata>;
@@ -16,6 +31,26 @@ interface MetadataCacheState {
     hasMetadata: (key: string) => boolean;
     hasModalMetadata: (key: string) => boolean;
     prefetchAll: (api: MetadataApiClient) => Promise<void>;
+    /**
+     * Remove cached entries belonging to a specific addon. Used by the
+     * hot-swap subscriber when the kernel announces a manifest change.
+     *
+     * Returns the number of entries removed across both caches, which is
+     * useful for tests and observability — `0` means the cache had nothing
+     * to flush (the addon either hadn't been hit yet or uses a key
+     * convention the default matcher doesn't recognise; pass a custom
+     * `matcher` if your host namespaces differently).
+     *
+     * Also resets `prefetched` to `false` so the next mount re-runs
+     * `prefetchAll()` and the `metadataVersion` is allowed to advance to
+     * the kernel's freshly-bumped hash.
+     */
+    invalidateAddon: (addonKey: string, matcher?: AddonKeyMatcher) => number;
+    /**
+     * Remove every cached entry. Heavier hammer for hosts that prefer a
+     * blanket flush on hot-swap rather than per-addon scoping.
+     */
+    clearAll: () => void;
 }
 export declare const useMetadataCache: import("zustand").UseBoundStore<Omit<import("zustand").StoreApi<MetadataCacheState>, "setState" | "persist"> & {
     setState(partial: MetadataCacheState | Partial<MetadataCacheState> | ((state: MetadataCacheState) => MetadataCacheState | Partial<MetadataCacheState>), replace?: false | undefined): unknown;

package/dist/metadata-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"metadata-cache.d.ts","sourceRoot":"","sources":["../src/metadata-cache.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED,UAAU,kBAAkB;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IACvD,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IAC5D,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAC3D,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAChE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACrC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC1C,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzD;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;EAwE5B,CAAA"}
+{"version":3,"file":"metadata-cache.d.ts","sourceRoot":"","sources":["../src/metadata-cache.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IAC9B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,CAAA;KAAE,CAAC,CAAA;CAC7D;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAA;AAE7E;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQlF;AAED,UAAU,kBAAkB;IACxB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAA;IACzC,eAAe,EAAE,MAAM,CAAA;IACvB,UAAU,EAAE,OAAO,CAAA;IACnB,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IACvD,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,GAAG,SAAS,CAAA;IAC5D,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAC3D,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAA;IAChE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IACrC,gBAAgB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC1C,WAAW,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD;;;;;;;;;;;;;OAaG;IACH,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,KAAK,MAAM,CAAA;IACxE;;;OAGG;IACH,QAAQ,EAAE,MAAM,IAAI,CAAA;CACvB;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;EAiH5B,CAAA"}

package/dist/metadata-cache.js

@@ -8,6 +8,20 @@
 // never invokes prefetchAll, the `api` dep is not required.
 import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
+/**
+ * Default matcher used by {@link MetadataCacheState.invalidateAddon}.
+ * Mirrors the convention used by the kernel installer when it scopes
+ * model metadata under an addon's key.
+ */
+export function defaultAddonKeyMatcher(cacheKey, addonKey) {
+    if (!addonKey)
+        return false;
+    if (cacheKey === addonKey)
+        return true;
+    return (cacheKey.startsWith(`${addonKey}.`) ||
+        cacheKey.startsWith(`${addonKey}:`) ||
+        cacheKey.startsWith(`${addonKey}/`));
+}
 export const useMetadataCache = create()(persist((set, get) => ({
     cache: {},
     modalCache: {},
@@ -27,6 +41,47 @@ export const useMetadataCache = create()(persist((set, get) => ({
     },
     hasMetadata: (key) => key in get().cache,
     hasModalMetadata: (key) => key in get().modalCache,
+    invalidateAddon: (addonKey, matcher = defaultAddonKeyMatcher) => {
+        if (!addonKey)
+            return 0;
+        let removed = 0;
+        const state = get();
+        const nextCache = {};
+        for (const [key, value] of Object.entries(state.cache)) {
+            if (matcher(key, addonKey)) {
+                removed += 1;
+                continue;
+            }
+            nextCache[key] = value;
+        }
+        const nextModalCache = {};
+        for (const [key, value] of Object.entries(state.modalCache)) {
+            if (matcher(key, addonKey)) {
+                removed += 1;
+                continue;
+            }
+            nextModalCache[key] = value;
+        }
+        if (removed === 0)
+            return 0;
+        set({
+            cache: nextCache,
+            modalCache: nextModalCache,
+            // Allow prefetchAll() to re-run so we pick up the new
+            // metadataVersion the kernel emits alongside the
+            // bumped manifest.
+            prefetched: false,
+        });
+        return removed;
+    },
+    clearAll: () => {
+        set({
+            cache: {},
+            modalCache: {},
+            metadataVersion: '',
+            prefetched: false,
+        });
+    },
     prefetchAll: async (api) => {
         if (get().prefetched)
             return;

package/dist/types.d.ts

@@ -74,6 +74,20 @@ export interface ColumnDefinition {
         icon?: string;
         color?: string;
     }[];
+    /**
+     * FK target model. When the kernel auto-derives this from a
+     * belongs_to relation (or an author sets it explicitly), the SDK
+     * resolves the column's options against `/api/options/<ref>?field=id`
+     * via `useOptionsResolver`. Wins over `searchEndpoint` for select
+     * widgets — `searchEndpoint` stays as the legacy escape hatch.
+     */
+    ref?: string;
+    /**
+     * Server-side validation rules the SDK can also pre-flight in the
+     * form layer. `custom` may be a literal slug or a $org.<key>
+     * reference resolved through the OrgConfigProvider.
+     */
+    validation?: FieldValidation;
 }
 export interface ActionCondition {
     field: string;
@@ -101,6 +115,12 @@ export interface ActionFieldDef {
     searchEndpoint?: string;
     validation?: FieldValidation;
     widget?: FieldWidget | string;
+    /**
+     * FK target model — same semantics as ColumnDefinition.ref. When
+     * present, DynamicForm resolves the field's options through
+     * `useOptionsResolver` against `/api/options/<ref>?field=id`.
+     */
+    ref?: string;
 }
 export interface ActionDefinition {
     key: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/use-options-resolver.d.ts

@@ -0,0 +1,87 @@
+export interface ResolvedOption {
+    /** Canonical id (server-side primary key). */
+    id: string | number;
+    /** Same as `id` — preserved for legacy frontend parity. */
+    value: string | number;
+    /** Display string. */
+    label: string;
+    /** Same as `label` — preserved for legacy frontend parity. */
+    name: string;
+    description?: string | null;
+    image?: string | null;
+    color?: string | null;
+    icon?: string | null;
+}
+export interface OptionsMeta {
+    /** 'static' for inline options, 'dynamic' for FK-resolved lists. */
+    type: 'static' | 'dynamic' | string;
+    /** Number of options the server returned in this batch. */
+    count: number;
+}
+export interface UseOptionsResolverArgs {
+    /**
+     * The owning model whose options endpoint is queried. Pass the model
+     * key (e.g. 'sales_orders'). Required — passing an empty string puts
+     * the hook in idle mode and no fetch fires.
+     */
+    modelKey: string;
+    /**
+     * Field on `modelKey` to resolve. Maps to `?field=<fieldKey>`.
+     */
+    fieldKey: string;
+    /**
+     * Optional FK target. When set the hook resolves against
+     * `/api/options/<ref>?field=id` instead of `/api/options/<modelKey>`.
+     * This is the canonical path the kernel auto-derives from
+     * `ColumnDef.Ref`. Prefer this over `endpoint`.
+     */
+    ref?: string;
+    /**
+     * Free-text query forwarded as `?q=`. Empty values are skipped so the
+     * server returns the first page unfiltered.
+     */
+    query?: string;
+    /**
+     * Server-side pagination cap. Defaults to 50 (kernel
+     * DefaultOptionsLimit) if omitted.
+     */
+    limit?: number;
+    /**
+     * Toggle to disable fetching entirely (e.g. while a parent row is
+     * still loading). Defaults to true.
+     */
+    enabled?: boolean;
+    /**
+     * Escape hatch for callers that need a non-canonical URL — e.g.
+     * legacy `/options/<custom>?...`. When set it overrides `ref` and
+     * `modelKey` for the fetch path. The query string is built from
+     * `fieldKey` / `query` / `limit` exactly the same way.
+     */
+    endpoint?: string;
+}
+export interface UseOptionsResolverResult {
+    options: ResolvedOption[];
+    meta: OptionsMeta | null;
+    loading: boolean;
+    error: Error | null;
+    /** Forces a refetch. Useful after a parent record updates. */
+    refetch: () => void;
+}
+/**
+ * Resolves select options for a field via the canonical
+ * `/api/options/:model?field=…` endpoint. Returns the v0.9.0 envelope
+ * `{ data, meta: { type, count } }` projected into a stable shape.
+ *
+ * The hook is intentionally minimal: it does NOT debounce `query`
+ * (callers should hold the controlled value and pass it post-debounce)
+ * and does NOT cache across hook instances (apps that need shared state
+ * compose this with TanStack Query in their own layer).
+ */
+export declare function useOptionsResolver(args: UseOptionsResolverArgs): UseOptionsResolverResult;
+/**
+ * Normalizes the wire shape into ResolvedOption. The kernel returns dual
+ * id/value and label/name fields for legacy parity — we accept either
+ * and surface a stable shape downstream.
+ */
+export declare function projectOption(raw: any): ResolvedOption;
+//# sourceMappingURL=use-options-resolver.d.ts.map

package/dist/use-options-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-options-resolver.d.ts","sourceRoot":"","sources":["../src/use-options-resolver.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,MAAM,WAAW,WAAW;IACxB,oEAAoE;IACpE,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,sBAAsB;IACnC;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,wBAAwB;IACrC,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;IACnB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,IAAI,CAAA;CACtB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAiHzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,GAAG,GAAG,cAAc,CAatD"}

package/dist/use-options-resolver.js

@@ -0,0 +1,147 @@
+// useOptionsResolver — single hook the SDK uses to fetch select options
+// for a metadata-driven field. Replaces the ad-hoc `/data/<model>` reads
+// that DynamicForm and DynamicRelation used to do.
+//
+// Contract (matches kernel ≥ v0.9.0):
+//   GET /api/options/:model?field=<key>&q=<text>&limit=<n>
+//   →  { success: true, data: Option[], meta: { type: 'static'|'dynamic', count } }
+//
+// The hook prefers `ColumnDef.Ref` (auto-derived by the kernel from
+// belongs_to relations) over a hand-wired `searchEndpoint`. Apps that
+// adopt Ref via the kernel auto-derivation get the right behaviour for
+// free; legacy callers that still ship `searchEndpoint` keep working.
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { useApi } from './api-context';
+/**
+ * Resolves select options for a field via the canonical
+ * `/api/options/:model?field=…` endpoint. Returns the v0.9.0 envelope
+ * `{ data, meta: { type, count } }` projected into a stable shape.
+ *
+ * The hook is intentionally minimal: it does NOT debounce `query`
+ * (callers should hold the controlled value and pass it post-debounce)
+ * and does NOT cache across hook instances (apps that need shared state
+ * compose this with TanStack Query in their own layer).
+ */
+export function useOptionsResolver(args) {
+    const { modelKey, fieldKey, ref, query, limit, enabled = true, endpoint, } = args;
+    const api = useApi();
+    const [options, setOptions] = useState([]);
+    const [meta, setMeta] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // refreshKey is bumped by `refetch` to force the effect to re-run
+    // even when none of the input args changed.
+    const [refreshKey, setRefreshKey] = useState(0);
+    // The URL the hook hits. Ref wins over modelKey because the kernel's
+    // auto-derivation makes ref the canonical pointer; a manual endpoint
+    // wins over both as the explicit override.
+    const url = useMemo(() => {
+        if (endpoint)
+            return endpoint;
+        if (ref)
+            return `/options/${ref}`;
+        if (!modelKey)
+            return '';
+        return `/options/${modelKey}`;
+    }, [endpoint, ref, modelKey]);
+    // The field to query. When using `ref` the canonical lookup field is
+    // `id` (FK targets the target model's PK), unless the caller wants
+    // to override that explicitly via `fieldKey`. We only inject the `id`
+    // default when `ref` is set AND `fieldKey` is empty.
+    const effectiveField = useMemo(() => {
+        if (fieldKey)
+            return fieldKey;
+        if (ref)
+            return 'id';
+        return '';
+    }, [fieldKey, ref]);
+    // Track the in-flight controller so a new fetch can abort the
+    // previous one — matters for typeahead callers passing changing `query`.
+    const abortRef = useRef(null);
+    useEffect(() => {
+        if (!enabled || !url || !effectiveField) {
+            setOptions([]);
+            setMeta(null);
+            setLoading(false);
+            setError(null);
+            return;
+        }
+        // Cancel any pending request before issuing a new one.
+        abortRef.current?.abort();
+        const controller = new AbortController();
+        abortRef.current = controller;
+        setLoading(true);
+        setError(null);
+        const params = { field: effectiveField };
+        if (query)
+            params.q = query;
+        if (typeof limit === 'number' && limit > 0)
+            params.limit = limit;
+        api.get(url, { params, signal: controller.signal })
+            .then((res) => {
+            if (controller.signal.aborted)
+                return;
+            const body = res.data;
+            if (!body || body.success !== true) {
+                throw new Error(body?.message || 'options resolver: unsuccessful response');
+            }
+            const rawOptions = Array.isArray(body.data) ? body.data : [];
+            const projected = rawOptions.map(projectOption);
+            setOptions(projected);
+            // v0.9.0 envelope: meta.type / meta.count. We tolerate
+            // older deployments that still emit a root-level `type`
+            // by reading either spot — the projection prefers the
+            // canonical location so the SDK guides apps to the new
+            // shape without breaking grace-period upgrades.
+            const metaPayload = body.meta && typeof body.meta === 'object'
+                ? body.meta
+                : { type: body.type, count: rawOptions.length };
+            setMeta({
+                type: metaPayload?.type ?? 'dynamic',
+                count: typeof metaPayload?.count === 'number'
+                    ? metaPayload.count
+                    : rawOptions.length,
+            });
+        })
+            .catch((err) => {
+            if (controller.signal.aborted)
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setOptions([]);
+            setMeta(null);
+        })
+            .finally(() => {
+            if (!controller.signal.aborted)
+                setLoading(false);
+        });
+        return () => {
+            controller.abort();
+        };
+    }, [api, url, effectiveField, query, limit, enabled, refreshKey]);
+    return {
+        options,
+        meta,
+        loading,
+        error,
+        refetch: () => setRefreshKey((k) => k + 1),
+    };
+}
+/**
+ * Normalizes the wire shape into ResolvedOption. The kernel returns dual
+ * id/value and label/name fields for legacy parity — we accept either
+ * and surface a stable shape downstream.
+ */
+export function projectOption(raw) {
+    const id = raw?.id ?? raw?.value ?? '';
+    const label = String(raw?.label ?? raw?.name ?? id ?? '');
+    return {
+        id,
+        value: raw?.value ?? id,
+        label,
+        name: String(raw?.name ?? label),
+        description: raw?.description ?? null,
+        image: raw?.image ?? null,
+        color: raw?.color ?? null,
+        icon: raw?.icon ?? null,
+    };
+}

package/dist/use-org-config-bridge.d.ts

@@ -0,0 +1,28 @@
+export interface OrgConfigBridge {
+    /** Resolves a `$org.<key>` reference (or plain key) to a literal id. */
+    resolveValidator: (refOrKey: string) => string | null;
+    /** When true the app actually has a provider mounted. */
+    available: boolean;
+}
+/**
+ * Apps that consume `runtime-react` AND `@asteby/metacore-app-providers`
+ * call this once near the root (typically inside the OrgConfigProvider
+ * children) so the SDK reads the same resolver. Hosts without an org
+ * provider can ignore this entirely; the SDK's null bridge keeps every
+ * call returning `null` so $org.<key> tokens stay verbatim in the form
+ * — same fallback the kernel uses for unresolved references.
+ */
+export declare function setOrgConfigBridge(bridge: OrgConfigBridge | null): void;
+/**
+ * Returns the active bridge. Pure read — no React hook so it can be
+ * called from non-component code (zod schema builders, helpers).
+ */
+export declare function getOrgConfigBridge(): OrgConfigBridge;
+/**
+ * Resolves a Validation token into the validator identifier the SDK
+ * should apply. Returns the resolved literal when the org config knows
+ * the key, or the original token when it doesn't (so apps can decide).
+ * Plain literals (no `$org.` prefix) pass through.
+ */
+export declare function resolveValidatorToken(token: string | undefined | null): string | null;
+//# sourceMappingURL=use-org-config-bridge.d.ts.map

package/dist/use-org-config-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-org-config-bridge.d.ts","sourceRoot":"","sources":["../src/use-org-config-bridge.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,eAAe;IAC5B,wEAAwE;IACxE,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAA;IACrD,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAA;CACrB;AASD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI,QAEhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAKrF"}