@almadar/runtime 6.54.0 → 6.56.0

package/dist/{OrbitalServerRuntime-Cz5MiWKB.d.ts → OrbitalServerRuntime-Bh4fHBkb.d.ts}

@@ -1,5 +1,5 @@
 import { Router } from 'express';
-import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, d as TraitState, C as ConfigContext, e as TransitionResult, f as EvaluationContextExtensions, E as EffectHandlers } from './types-BcPORH_x.js';
+import { I as IEventBus, R as RuntimeEvent, a as EventListener, U as Unsubscribe, T as TraitDefinition, b as RuntimeConfig, c as TransitionObserver, d as TraitState, C as ConfigContext, e as TransitionResult, f as EvaluationContextExtensions, E as EffectHandlers } from './types-BWENk-qT.js';
 import { EventPayload, EventId, EntityRow, UserContext, Orbital, ServiceCallResult, TraitConfig, DeclaredTraitConfig, Entity, OrbitalSchema, Trait, PatternConfig, ResolvedPatternProps, SExpr, BusEventSource, RawUserClaims, OrbitalDefinition, TraitTick } from '@almadar/core';
 
 /**
@@ -899,11 +899,14 @@ declare class InMemoryPersistence implements PersistenceAdapter {
  * registry validation lives in `orbital validate` / `lolo` parse, not here.
  */
 type ClientRenderUITuple = ['render-ui', string, PatternConfig | null] | ['render-ui', string, PatternConfig | null, ResolvedPatternProps] | ['render-ui', string, PatternConfig | null, ResolvedPatternProps | undefined, number | undefined];
-type ClientNavigateTuple = ['navigate', string] | ['navigate', string, Record<string, string> | undefined];
+type ClientNavigateTuple = ['navigate', string] | ['navigate', string, Record<string, string> | undefined] | ['navigate', string, Record<string, string> | undefined, {
+    crumb?: string;
+}];
+type ClientNavigateBackTuple = ['navigate-back'];
 type ClientNotifyTuple = ['notify', string, string | SExpr | undefined] | ['notify', string, string | SExpr | undefined, {
     type?: string;
 }];
-type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNotifyTuple;
+type ClientEffectTuple = ClientRenderUITuple | ClientNavigateTuple | ClientNavigateBackTuple | ClientNotifyTuple;
 
 /** @deprecated Use OrbitalSchema from @almadar/core */
 type RuntimeOrbitalSchema = OrbitalSchema;
@@ -1296,6 +1299,25 @@ declare class OrbitalServerRuntime {
      * Clear the preprocessing cache.
      */
     clearPreprocessCache(): void;
+    /**
+     * Resolve an entity definition by name across every registered orbital's
+     * resolved primary entity. Used by relation-option injection to find the
+     * relation TARGET entity (usually another orbital's primary).
+     */
+    private findEntityDefByName;
+    /**
+     * Server-side relation-option injection — the interpreter's mirror of the
+     * compiled path's build-time `relationsData` generation (orbital-rust
+     * registry.rs). Walks a render-ui pattern tree; for every form pattern
+     * (form / form-section / inline-edit-form / wizard-step) and detail-panel
+     * whose linked entity declares relation-typed fields among the node's
+     * `fields`, reads the relation TARGET entity's rows from the persistence
+     * adapter and attaches `relationsData: { <field>: [{value, label}] }`.
+     * Label contract identical to codegen: `name || title || id`. Options are
+     * re-read on every render-ui, so they refresh with each re-render exactly
+     * like any fetch. Authored `relationsData` is never overwritten.
+     */
+    private injectRelationOptions;
     /**
      * Register a single orbital
      */
@@ -1471,4 +1493,4 @@ declare class OrbitalServerRuntime {
  */
 declare function createOrbitalServerRuntime(config?: OrbitalServerRuntimeConfig): OrbitalServerRuntime;
 
-export { normalizeEventKey as A, parseNamespacedEvent as B, preprocessSchema as C, processEvent as D, type EntitySharingMap as E, type ClientEffectTuple as F, type ClientNavigateTuple as G, type ClientNotifyTuple as H, type ImportChainLike as I, type ClientRenderUITuple as J, type EffectResult as K, type LoadResult as L, type LiveBroadcastItem as M, type LoaderConfig as N, type OrbitalEventRequest as O, type PersistenceAdapter as P, OrbitalServerRuntime as Q, type RegisteredOrbital as R, type SchemaLoader as S, type RuntimeTraitTick as T, type UnifiedLoaderOptions as U, createOrbitalServerRuntime as V, type LoadedSchema as a, type LoadedOrbital as b, EventBus as c, type EventNamespaceMap as d, InMemoryPersistence as e, type OrbitalEventResponse as f, type OrbitalServerRuntimeConfig as g, type PreprocessOptions as h, type PreprocessResult as i, type PreprocessedSchema as j, type ProcessEventOptions as k, type RuntimeOrbital as l, type RuntimeOrbitalSchema as m, type RuntimeTrait as n, StateMachineManager as o, collectDeclaredConfigDefaults as p, collectDeclaredEntityDefaults as q, createInitialTraitState as r, findInitialState as s, findTransition as t, getIsolatedCollectionName as u, getNamespacedEvent as v, isBrowser as w, isElectron as x, isNamespacedEvent as y, isNode as z };
+export { normalizeEventKey as A, parseNamespacedEvent as B, preprocessSchema as C, processEvent as D, type EntitySharingMap as E, type ClientEffectTuple as F, type ClientNavigateBackTuple as G, type ClientNavigateTuple as H, type ImportChainLike as I, type ClientNotifyTuple as J, type ClientRenderUITuple as K, type LoadResult as L, type EffectResult as M, type LiveBroadcastItem as N, type OrbitalEventRequest as O, type PersistenceAdapter as P, type LoaderConfig as Q, type RegisteredOrbital as R, type SchemaLoader as S, OrbitalServerRuntime as T, type UnifiedLoaderOptions as U, type RuntimeTraitTick as V, createOrbitalServerRuntime as W, type LoadedSchema as a, type LoadedOrbital as b, EventBus as c, type EventNamespaceMap as d, InMemoryPersistence as e, type OrbitalEventResponse as f, type OrbitalServerRuntimeConfig as g, type PreprocessOptions as h, type PreprocessResult as i, type PreprocessedSchema as j, type ProcessEventOptions as k, type RuntimeOrbital as l, type RuntimeOrbitalSchema as m, type RuntimeTrait as n, StateMachineManager as o, collectDeclaredConfigDefaults as p, collectDeclaredEntityDefaults as q, createInitialTraitState as r, findInitialState as s, findTransition as t, getIsolatedCollectionName as u, getNamespacedEvent as v, isBrowser as w, isElectron as x, isNamespacedEvent as y, isNode as z };

package/dist/OrbitalServerRuntime.d.ts

@@ -1,4 +1,4 @@
 import 'express';
-export { F as ClientEffectTuple, G as ClientNavigateTuple, H as ClientNotifyTuple, J as ClientRenderUITuple, K as EffectResult, e as InMemoryPersistence, M as LiveBroadcastItem, N as LoaderConfig, O as OrbitalEventRequest, f as OrbitalEventResponse, Q as OrbitalServerRuntime, g as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, T as RuntimeTraitTick, p as collectDeclaredConfigDefaults, V as createOrbitalServerRuntime } from './OrbitalServerRuntime-Cz5MiWKB.js';
-import './types-BcPORH_x.js';
+export { F as ClientEffectTuple, G as ClientNavigateBackTuple, H as ClientNavigateTuple, J as ClientNotifyTuple, K as ClientRenderUITuple, M as EffectResult, e as InMemoryPersistence, N as LiveBroadcastItem, Q as LoaderConfig, O as OrbitalEventRequest, f as OrbitalEventResponse, T as OrbitalServerRuntime, g as OrbitalServerRuntimeConfig, P as PersistenceAdapter, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, V as RuntimeTraitTick, p as collectDeclaredConfigDefaults, W as createOrbitalServerRuntime } from './OrbitalServerRuntime-Bh4fHBkb.js';
+import './types-BWENk-qT.js';
 import '@almadar/core';

package/dist/OrbitalServerRuntime.js

@@ -1,5 +1,5 @@
-import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-DERIA6MO.js';
-export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-DERIA6MO.js';
+import { createTickScheduler, EventBus, createUnifiedLoader, MockPersistenceAdapter, InMemoryPersistence, preprocessSchema, normalizeCallSiteConfigToValues, StateMachineManager, parseDurationString, validateEventPayload, formatPayloadValidationError, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, EffectExecutor } from './chunk-XY5BLZKS.js';
+export { InMemoryPersistence, collectDeclaredConfigDefaults } from './chunk-XY5BLZKS.js';
 import { isValidCronExpression } from './chunk-OU3ITB5S.js';
 import { createContextFromBindings, resolveCallSitePayloadCaptures, applyRowAccess, checkMutationAccess, accessDeniedMessage } from './chunk-ZJ62H3ES.js';
 import './chunk-T4VDAB4C.js';
@@ -10,6 +10,7 @@ import * as nodeModule from 'module';
 import { evaluateListenPayloadExpr, evaluateGuard, evaluate } from '@almadar/evaluator';
 import { DEFAULT_VIEWER, buildResolvedTraitConfigs, isInlineTrait, isEntityCall, applyListenPayloadMapping, personaFromIdentityRow, normalizeUserContext, isRuntimeEntity, isPageReference } from '@almadar/core';
 import { ownerFieldsFromSchema, identityEntityName, entityAccessPolicies } from '@almadar/core/mock';
+import { getPatternFieldsContract } from '@almadar/core/patterns';
 
 // src/identity/routing.ts
 function eventRouteKey(eventName, eventId) {
@@ -527,6 +528,81 @@ var OrbitalServerRuntime = class {
   clearPreprocessCache() {
     this.preprocessedCache.clear();
   }
+  /**
+   * Resolve an entity definition by name across every registered orbital's
+   * resolved primary entity. Used by relation-option injection to find the
+   * relation TARGET entity (usually another orbital's primary).
+   */
+  findEntityDefByName(name) {
+    for (const registered of this.orbitals.values()) {
+      if (registered.entity?.name === name) return registered.entity;
+    }
+    return void 0;
+  }
+  /**
+   * Server-side relation-option injection — the interpreter's mirror of the
+   * compiled path's build-time `relationsData` generation (orbital-rust
+   * registry.rs). Walks a render-ui pattern tree; for every form pattern
+   * (form / form-section / inline-edit-form / wizard-step) and detail-panel
+   * whose linked entity declares relation-typed fields among the node's
+   * `fields`, reads the relation TARGET entity's rows from the persistence
+   * adapter and attaches `relationsData: { <field>: [{value, label}] }`.
+   * Label contract identical to codegen: `name || title || id`. Options are
+   * re-read on every render-ui, so they refresh with each re-render exactly
+   * like any fetch. Authored `relationsData` is never overwritten.
+   */
+  async injectRelationOptions(pattern, registered, traitName) {
+    if (pattern === null || typeof pattern !== "object") return;
+    const linkedEntityName = registered.traits.find((t) => t.name === traitName)?.linkedEntity ?? registered.entity?.name;
+    if (!linkedEntityName) return;
+    const entityDef = this.findEntityDefByName(linkedEntityName);
+    if (!entityDef?.fields) return;
+    const relationTargets = /* @__PURE__ */ new Map();
+    for (const field of entityDef.fields) {
+      if (field.type === "relation" && field.relation?.entity && field.name) {
+        relationTargets.set(field.name, field.relation.entity);
+      }
+    }
+    if (relationTargets.size === 0) return;
+    const visit = async (node) => {
+      if (node === null || node === void 0 || typeof node !== "object") return;
+      if (Array.isArray(node)) {
+        for (const child of node) await visit(child);
+        return;
+      }
+      const record = node;
+      const nodeType = record["type"];
+      const fields = record["fields"];
+      if (typeof nodeType === "string" && // Which patterns consume entity-bound field lists is DECLARED per
+      // component via `@fieldsContract` and read from the pattern registry
+      // — never a hardcoded name list. Both contracts get relation options
+      // (form selects need choices; display fields need label resolution).
+      getPatternFieldsContract(nodeType) !== void 0 && Array.isArray(fields) && record["relationsData"] === void 0) {
+        const relationsData = {};
+        for (const fieldEntry of fields) {
+          const fieldName = typeof fieldEntry === "string" ? fieldEntry : fieldEntry !== null && typeof fieldEntry === "object" && !Array.isArray(fieldEntry) ? String(
+            fieldEntry["name"] ?? fieldEntry["key"] ?? ""
+          ) : "";
+          const targetEntity = fieldName ? relationTargets.get(fieldName) : void 0;
+          if (!targetEntity) continue;
+          try {
+            const rows = await this.persistence.list(targetEntity);
+            relationsData[fieldName] = rows.map((r) => ({
+              value: String(r.id ?? ""),
+              label: String(r.name ?? r.title ?? r.id ?? "")
+            }));
+          } catch {
+          }
+        }
+        if (Object.keys(relationsData).length > 0) {
+          record["relationsData"] = relationsData;
+        }
+      }
+      const children = record["children"];
+      if (children !== void 0) await visit(children);
+    };
+    await visit(pattern);
+  }
   /**
    * Register a single orbital
    */
@@ -1675,7 +1751,8 @@ var OrbitalServerRuntime = class {
         }
       },
       // Client-side effects - collect for forwarding to client
-      renderUI: (slot, pattern, props, priority) => {
+      renderUI: async (slot, pattern, props, priority) => {
+        await this.injectRelationOptions(pattern, registered, traitName);
         const patternNode = pattern !== null && typeof pattern === "object" && !Array.isArray(pattern) ? pattern : null;
         const patternEntity = patternNode?.entity;
         const entityRow = patternEntity !== null && typeof patternEntity === "object" && !Array.isArray(patternEntity) ? patternEntity : null;
@@ -1689,8 +1766,15 @@ var OrbitalServerRuntime = class {
         });
         pushClientEffect(["render-ui", slot, pattern, props, priority]);
       },
-      navigate: (path, params) => {
-        pushClientEffect(["navigate", path, params]);
+      navigate: (path, params, crumb) => {
+        if (crumb !== void 0) {
+          pushClientEffect(["navigate", path, params, { crumb }]);
+        } else {
+          pushClientEffect(["navigate", path, params]);
+        }
+      },
+      navigateBack: () => {
+        pushClientEffect(["navigate-back"]);
       },
       notify: (message, type) => {
         if (this.config.debug) {

package/dist/ServerBridge.d.ts

@@ -1,4 +1,4 @@
-import { I as IEventBus } from './types-BcPORH_x.js';
+import { I as IEventBus } from './types-BWENk-qT.js';
 import { EventPayload } from '@almadar/core';
 
 /**

package/dist/{chunk-DERIA6MO.js → chunk-XY5BLZKS.js}

@@ -886,12 +886,13 @@ var StateMachineManager = class {
 
 // src/types.ts
 var HANDLER_MANIFEST = {
-  client: ["render-ui", "render", "navigate", "notify", "emit", "set", "log", "ref", "deref", "watch", "send-server", "browser/open-file-picker", "browser/clipboard-read", "browser/clipboard-write", "browser/geolocation-current"],
+  client: ["render-ui", "render", "navigate", "navigate-back", "notify", "emit", "set", "log", "ref", "deref", "watch", "send-server", "browser/open-file-picker", "browser/clipboard-read", "browser/clipboard-write", "browser/geolocation-current"],
   server: ["persist", "fetch", "fetch-stream", "call-service", "emit", "set", "spawn", "despawn", "log", "ref", "deref", "swap!", "atomic", "os/watch-files", "os/watch-process", "os/watch-port", "os/watch-http", "os/watch-cron", "os/watch-signal", "os/watch-env", "os/debounce"],
   test: [
     "render-ui",
     "render",
     "navigate",
+    "navigate-back",
     "notify",
     "emit",
     "set",
@@ -1025,6 +1026,7 @@ var EffectExecutor = class _EffectExecutor {
       "render-ui": this.handlers.renderUI,
       "render": this.handlers.renderUI,
       "navigate": this.handlers.navigate,
+      "navigate-back": this.handlers.navigateBack,
       "notify": this.handlers.notify,
       "log": this.handlers.log,
       "ref": this.handlers.ref,
@@ -1563,7 +1565,7 @@ var EffectExecutor = class _EffectExecutor {
           const pattern = patternRaw === null ? null : patternRaw;
           const props = args[2];
           const priority = args[3];
-          this.handlers.renderUI(slot, pattern, props, priority);
+          await this.handlers.renderUI(slot, pattern, props, priority);
         } else {
           this.logUnsupported("render-ui");
         }
@@ -1572,13 +1574,27 @@ var EffectExecutor = class _EffectExecutor {
       case "navigate": {
         if (this.handlers.navigate) {
           const path = args[0];
+          if (typeof path !== "string" || path === "") {
+            effectLog.warn("navigate-path-unresolved", { pathType: typeof path });
+            break;
+          }
           const params = args[1];
-          this.handlers.navigate(path, params);
+          const options = args[2];
+          const crumb = options && typeof options.crumb === "string" && options.crumb !== "" ? options.crumb : void 0;
+          this.handlers.navigate(path, params, crumb);
         } else {
           this.logUnsupported("navigate");
         }
         break;
       }
+      case "navigate-back": {
+        if (this.handlers.navigateBack) {
+          this.handlers.navigateBack();
+        } else {
+          this.logUnsupported("navigate-back");
+        }
+        break;
+      }
       case "notify": {
         if (this.handlers.notify) {
           const message = args[0];
@@ -2101,7 +2117,7 @@ var mockLog = createLogger("almadar:runtime:mock");
 var DEFAULT_MOCK_SEED = 42;
 var SEED_REFERENCE_TIMESTAMP = "2024-01-01T00:00:00.000Z";
 var MS_PER_DAY = 864e5;
-var MockPersistenceAdapter = class {
+var MockPersistenceAdapter = class _MockPersistenceAdapter {
   stores = /* @__PURE__ */ new Map();
   schemas = /* @__PURE__ */ new Map();
   idCounters = /* @__PURE__ */ new Map();
@@ -2349,6 +2365,7 @@ var MockPersistenceAdapter = class {
   // ============================================================================
   async create(entityType, data) {
     const store = this.getStore(entityType);
+    this.assertFileValuesWithinCeiling(entityType, data);
     const id = this.nextId(entityType);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const withDefaults = this.applyFieldDefaults(entityType, data);
@@ -2361,6 +2378,27 @@ var MockPersistenceAdapter = class {
     store.set(id, item);
     return { id };
   }
+  /**
+   * Mock-mode file storage ceiling: a `file`-typed value whose `url` is a
+   * `data:` URI keeps the whole payload in this in-memory/localStorage
+   * store. Above the ceiling the write is REJECTED with a clear error —
+   * never silently truncated or corrupted. Real deployments store bytes in
+   * object storage and keep only the URL, so the ceiling is mock-only.
+   */
+  static FILE_DATA_URI_CEILING_BYTES = 2 * 1024 * 1024;
+  assertFileValuesWithinCeiling(entityType, data) {
+    for (const [fieldName, value] of Object.entries(data)) {
+      if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
+      const candidate = value;
+      if (typeof candidate.url !== "string" || !candidate.url.startsWith("data:")) continue;
+      const bytes = typeof candidate.sizeBytes === "number" ? candidate.sizeBytes : candidate.url.length;
+      if (bytes > _MockPersistenceAdapter.FILE_DATA_URI_CEILING_BYTES) {
+        throw new Error(
+          `${entityType}.${fieldName}: the playground mock store cannot persist files larger than ${_MockPersistenceAdapter.FILE_DATA_URI_CEILING_BYTES / (1024 * 1024)}MB (got ${(bytes / (1024 * 1024)).toFixed(1)}MB). Use a smaller file - production deployments store file bytes in object storage instead of the row.`
+        );
+      }
+    }
+  }
   /**
    * Fill in any entity-declared field defaults that the caller omitted.
    * SAVE payloads coming from form-section only carry the fields the user
@@ -2382,6 +2420,7 @@ var MockPersistenceAdapter = class {
   }
   async update(entityType, id, data) {
     const store = this.getStore(entityType);
+    this.assertFileValuesWithinCeiling(entityType, data);
     const existing = store.get(id);
     if (!existing) {
       throw new Error(`Entity ${entityType} with id ${id} not found`);

package/dist/createOsHandlers.d.ts

@@ -1,4 +1,4 @@
-import { E as EffectHandlers } from './types-BcPORH_x.js';
+import { E as EffectHandlers } from './types-BWENk-qT.js';
 import { EventPayload } from '@almadar/core';
 
 /**

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { g as RuntimePatternValue, B as BindingContext, f as EvaluationContextExtensions, P as PatternProps, E as EffectHandlers, h as EffectContext, i as ExecutionEnvironment, j as EffectResult, T as TraitDefinition } from './types-BcPORH_x.js';
-export { k as BrowserFileMeta, l as BrowserFilePickerOptions, m as BrowserGeolocationOptions, n as BrowserGeolocationPosition, C as ConfigContext, o as Effect, a as EventListener, H as HANDLER_MANIFEST, I as IEventBus, b as RuntimeConfig, R as RuntimeEvent, d as TraitState, c as TransitionObserver, e as TransitionResult, U as Unsubscribe } from './types-BcPORH_x.js';
-import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital, P as PersistenceAdapter } from './OrbitalServerRuntime-Cz5MiWKB.js';
-export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, e as InMemoryPersistence, O as OrbitalEventRequest, f as OrbitalEventResponse, g as OrbitalServerRuntimeConfig, h as PreprocessOptions, i as PreprocessResult, j as PreprocessedSchema, k as ProcessEventOptions, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, o as StateMachineManager, p as collectDeclaredConfigDefaults, q as collectDeclaredEntityDefaults, r as createInitialTraitState, s as findInitialState, t as findTransition, u as getIsolatedCollectionName, v as getNamespacedEvent, w as isBrowser, x as isElectron, y as isNamespacedEvent, z as isNode, A as normalizeEventKey, B as parseNamespacedEvent, C as preprocessSchema, D as processEvent } from './OrbitalServerRuntime-Cz5MiWKB.js';
+import { g as RuntimePatternValue, B as BindingContext, f as EvaluationContextExtensions, P as PatternProps, E as EffectHandlers, h as EffectContext, i as ExecutionEnvironment, j as EffectResult, T as TraitDefinition } from './types-BWENk-qT.js';
+export { k as BrowserFileMeta, l as BrowserFilePickerOptions, m as BrowserGeolocationOptions, n as BrowserGeolocationPosition, C as ConfigContext, o as Effect, a as EventListener, H as HANDLER_MANIFEST, I as IEventBus, b as RuntimeConfig, R as RuntimeEvent, d as TraitState, c as TransitionObserver, e as TransitionResult, U as Unsubscribe } from './types-BWENk-qT.js';
+import { U as UnifiedLoaderOptions, S as SchemaLoader, I as ImportChainLike, L as LoadResult, a as LoadedSchema, b as LoadedOrbital, P as PersistenceAdapter } from './OrbitalServerRuntime-Bh4fHBkb.js';
+export { E as EntitySharingMap, c as EventBus, d as EventNamespaceMap, e as InMemoryPersistence, O as OrbitalEventRequest, f as OrbitalEventResponse, g as OrbitalServerRuntimeConfig, h as PreprocessOptions, i as PreprocessResult, j as PreprocessedSchema, k as ProcessEventOptions, R as RegisteredOrbital, l as RuntimeOrbital, m as RuntimeOrbitalSchema, n as RuntimeTrait, o as StateMachineManager, p as collectDeclaredConfigDefaults, q as collectDeclaredEntityDefaults, r as createInitialTraitState, s as findInitialState, t as findTransition, u as getIsolatedCollectionName, v as getNamespacedEvent, w as isBrowser, x as isElectron, y as isNamespacedEvent, z as isNode, A as normalizeEventKey, B as parseNamespacedEvent, C as preprocessSchema, D as processEvent } from './OrbitalServerRuntime-Bh4fHBkb.js';
 import { EvaluationContext, SExpressionEvaluator } from '@almadar/evaluator';
 export { EvaluationContext, createMinimalContext } from '@almadar/evaluator';
 import { RenderBindingMarker, SExpr, TraitConfigObject, EventPayload, PatternConfig, EntityId, EntityField, EntityRow, EntityPersistence, ServiceParams, EntityAccessPolicies, PayloadField, OrbitalDefinition, OrbitalSchema } from '@almadar/core';
@@ -499,10 +499,14 @@ interface CreateClientEffectHandlersOptions {
     eventBus: ClientEventBus;
     /** Slot setter for render-ui effects */
     slotSetter: SlotSetter;
-    /** Navigate function for navigate effects */
+    /** Navigate function for navigate effects. `crumb` labels the target
+     * page's navigation-stack entry (from the effect's `{ crumb: … }`
+     * options). */
     navigate?: (path: string, params?: {
         [key: string]: string;
-    }) => void;
+    }, crumb?: string) => void;
+    /** Navigate-back function: pop the orbital-scoped navigation stack. */
+    navigateBack?: () => void;
     /** Notify function for notification effects */
     notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
     /**
@@ -686,6 +690,15 @@ declare class MockPersistenceAdapter implements PersistenceAdapter {
     create(entityType: string, data: EntityRow): Promise<{
         id: string;
     }>;
+    /**
+     * Mock-mode file storage ceiling: a `file`-typed value whose `url` is a
+     * `data:` URI keeps the whole payload in this in-memory/localStorage
+     * store. Above the ceiling the write is REJECTED with a clear error —
+     * never silently truncated or corrupted. Real deployments store bytes in
+     * object storage and keep only the URL, so the ceiling is mock-only.
+     */
+    private static readonly FILE_DATA_URI_CEILING_BYTES;
+    private assertFileValuesWithinCeiling;
     /**
      * Fill in any entity-declared field defaults that the caller omitted.
      * SAVE payloads coming from form-section only carry the fields the user

package/dist/index.js

@@ -1,5 +1,5 @@
-import { EffectExecutor } from './chunk-DERIA6MO.js';
-export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeCallSiteConfigToValues, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes } from './chunk-DERIA6MO.js';
+import { EffectExecutor } from './chunk-XY5BLZKS.js';
+export { EffectExecutor, EventBus, HANDLER_MANIFEST, InMemoryPersistence, MockPersistenceAdapter, StateMachineManager, TickScheduler, buildEmitsFromTraits, collectDeclaredConfigDefaults, collectDeclaredEntityDefaults, createInitialTraitState, createMockPersistence, createTestExecutor, createTickScheduler, createUnifiedLoader, findInitialState, findTransition, formatPayloadValidationError, getIsolatedCollectionName, getNamespacedEvent, isBrowser, isElectron, isNamespacedEvent, isNode, isValidDurationString, normalizeCallSiteConfigToValues, normalizeEventKey, parseDurationString, parseNamespacedEvent, preprocessSchema, processEvent, validateEventPayload, validatePayloadShapes } from './chunk-XY5BLZKS.js';
 export { cronMatches, cronMinuteKey, isValidCronExpression, parseCron, parseCronField } from './chunk-OU3ITB5S.js';
 import { createContextFromBindings, applyRowAccess, checkMutationAccess, accessDeniedMessage } from './chunk-ZJ62H3ES.js';
 export { CALLSITE_PAYLOAD_PREFIX, applyRowAccess, checkMutationAccess, containsBindings, createContextFromBindings, createMinimalContext, deferEntityBindings, extractBindings, interpolateProps, interpolateValue, resolveCallSitePayloadCaptures } from './chunk-ZJ62H3ES.js';
@@ -57,7 +57,7 @@ function sendServerEvent(orbital, event, payload) {
   }
 }
 function createClientEffectHandlers(options) {
-  const { eventBus, slotSetter, navigate, notify, sendServer, orbitalName = "" } = options;
+  const { eventBus, slotSetter, navigate, navigateBack, notify, sendServer, orbitalName = "" } = options;
   return {
     emit: (event, payload) => {
       const prefixedEvent = event.startsWith("UI:") ? event : `UI:${event}`;
@@ -87,6 +87,9 @@ function createClientEffectHandlers(options) {
       }
       log.warn("navigate-no-handler", { path });
     }),
+    navigateBack: navigateBack ?? (() => {
+      log.warn("navigate-back-no-handler");
+    }),
     notify: notify ?? ((msg, type) => {
       log.debug("notify", { type: type ?? null, message: msg });
     }),

package/dist/{types-BcPORH_x.d.ts → types-BWENk-qT.d.ts}

@@ -183,12 +183,20 @@ interface EffectHandlers {
     sendServer?: (event: string, payload?: EventPayload) => void;
     /** Render UI to a slot (client only). `pattern` is the post-interpolation
      * `PatternConfig` from the trait's `(render-ui slot pattern)` SExpr, or
-     * `null` when the trait clears the slot (`render-ui slot null`). */
-    renderUI?: (slot: string, pattern: PatternConfig | null, props?: PatternProps, priority?: number) => void;
-    /** Navigate to a route (client only) */
+     * `null` when the trait clears the slot (`render-ui slot null`).
+     * May be async: the server runtime injects relation option data
+     * (relationsData) read from the persistence adapter before pushing —
+     * the interpreter's mirror of codegen's build-time relationsData. */
+    renderUI?: (slot: string, pattern: PatternConfig | null, props?: PatternProps, priority?: number) => void | Promise<void>;
+    /** Navigate to a route (client only). `crumb` labels the navigation-stack
+     * entry the client pushes for the target page (from the effect's
+     * `{ crumb: … }` options). */
     navigate?: (path: string, params?: {
         [key: string]: string;
-    }) => void;
+    }, crumb?: string) => void;
+    /** Pop the orbital-scoped navigation stack and return to the previous
+     * entry (client only). */
+    navigateBack?: () => void;
     /** Show a notification (client: toast, server: log) */
     notify?: (message: string, type: 'success' | 'error' | 'warning' | 'info') => void;
     /** Log a message */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/runtime",
-  "version": "6.54.0",
+  "version": "6.56.0",
   "description": "Interpreted runtime for Almadar orbital applications (OrbitalServerRuntime)",
   "type": "module",
   "main": "./dist/index.js",
@@ -57,11 +57,11 @@
     "access": "public"
   },
   "dependencies": {
-    "@almadar/core": "^10.61.0",
+    "@almadar/core": "^10.64.0",
     "@almadar/evaluator": "^2.41.0",
     "@almadar/logger": "^1.11.0",
-    "@almadar/server": "^2.34.0",
-    "@almadar/std": "^16.176.0"
+    "@almadar/server": "^2.35.0",
+    "@almadar/std": "^16.180.0"
   },
   "peerDependencies": {
     "express": "^5.0.0"