@wix/himalaya-cli 0.1543.0 → 0.1545.0

package/templates/branded-lite/tier5-src/_shared/collection-service.ts

@@ -12,6 +12,8 @@ export interface CollectionSaving {
 type State = Record<string, unknown>;
 interface BackendCollection {
   restorePagesOnLoad?: boolean;
+  /** Opt in only for templates whose generated screens adopt the shared read status. */
+  readLifecycle?: boolean;
   /** Sees the load action's argument (the screen's onAppear params) BEFORE the query runs. A returned
    *  `{ filter, sort }` resets the criteria for that load (a screen that always opens on one view). */
   onLoad?(arg: unknown): CollectionCriteriaReset | void;
@@ -83,6 +85,8 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     })
     : [];
   let pendingFilter = '';
+  const requestedReadLifecycle = (def as { readLifecycle?: { refreshAction: string; statusPath: string } }).readLifecycle;
+  const hasReadLifecycle = !!requestedReadLifecycle || backend?.readLifecycle === true;
   const applyNavigationCriteria = (arg: unknown, state: State): boolean => {
     const input = object(arg);
     let changed = false;
@@ -144,16 +148,18 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     if (previewId && !rows.some(row => collectionId(row) === previewId)) previewId = '';
     const filterChoices = [{ id: 'all', label: copyParam('collection.all', 'All') }, ...(config.rowStyle === 'flat' ? [] : [{ id: 'saved', label: copyParam('collection.saved', 'Saved') }]),
       ...projected.filters.map(label => ({ id: `value:${label}`, label: copyParam(`collection.filter.${label}`, label) }))];
-    const loading = s.status === 'loading' || s.isLoading === true;
+    const readStatus = hasReadLifecycle ? s.readStatus as { hasSnapshot?: boolean; refreshing?: boolean } | undefined : undefined;
+    const loading = readStatus ? readStatus.refreshing === true && readStatus.hasSnapshot !== true : s.status === 'loading' || s.isLoading === true;
     // Older domain reducers expose `errored` rather than `isErrored`; backend
     // adapters can also intentionally keep their display status "ready" while
     // the query controller carries a recoverable failure. Treat each shape as
     // one collection state so the shared UI never renders a blank catalog.
     const backendState = backend?.controller.getState();
+    const read = backend?.readLifecycle ? s.readStatus as { hasSnapshot?: boolean; offline?: boolean; error?: string } | undefined : undefined;
     const provisional = backendState?.provisional === true;
-    const errored = s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
+    const errored = !!read?.error || (backend?.readLifecycle === true && !!backendState?.error) || s.status === 'error' || s.isErrored === true || s.errored === true || backendState?.status === 'error';
     const domainError = typeof s.error === 'string' ? s.error.trim() : '';
-    const queryError = typeof backendState?.error === 'string' ? backendState.error.trim() : '';
+    const queryError = read?.offline && !read.hasSnapshot ? 'This content isn’t available offline. Connect to load it.' : read?.error || (typeof backendState?.error === 'string' ? backendState.error.trim() : '');
     // Some domains carry their failure sentence in `emptyText` (portfolio, podcasts);
     // the screen folds that node into this block, so keep the domain's own words.
     const domainEmptyError = errored && typeof s.emptyText === 'string' ? s.emptyText.trim() : '';
@@ -178,7 +184,7 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     // "All" and the collection's own default (e.g. Upcoming) are both un-narrowed: Clear
     // resets to "All", so showing it on either would offer a reset that changes nothing.
     const narrowed = !!prefs.query.trim() || (prefs.filter !== 'all' && prefs.filter !== initialCollection(config).filter) || domainNarrowed;
-    const sourceEmpty = !loading && !errored && rows.length === 0 &&
+    const sourceEmpty = (backend?.readLifecycle !== true || backendState?.read.hasSnapshot === true) && !loading && !errored && rows.length === 0 &&
       (!(backend && config.backendQuery) || !narrowed) && !domainNarrowed;
     const emptySourceText = (typeof s.emptyText === 'string' && s.emptyText.trim()) || copyParam('collection.emptySource', 'Nothing here yet');
     // Chrome is noise over a small un-narrowed list (fewer than COLLECTION_CHROME_MIN_ITEMS
@@ -196,14 +202,15 @@ export function decorateCollection(name: string, def: { state: State; actions?:
       noPageError: s.pageError !== true,
       // Rows read from the device ahead of the live read are shown as they are: "saved offline" is what stays on
       // screen when the live read failed, not a first visit that is still loading.
-      noOffline: s.fromCache !== true || provisional,
+      noOffline: !(backend?.readLifecycle === true && backendState?.read.stale || s.fromCache === true) || provisional,
       noError: !errored,
       noRetry: !canRetry || signInRequired,
       noSignIn: !signInRequired,
       errorTitle: signInRequired ? copyParam('collection.signInTitle', 'Sign in to see this') : copyParam('collection.loadErrorTitle', 'This collection could not load'),
       errorMessage,
-      // A skeleton only with nothing to show: a search re-running over the rows on screen keeps them.
-      noLoading: !loading || rows.length > 0,
+      isLoading: loading, notLoading: !loading,
+      // Legacy searches retain visible rows; opted-in reads also retain valid empty snapshots.
+      noLoading: !loading || rows.length > 0 || (backend?.readLifecycle === true && backendState?.read.hasSnapshot === true),
       // De-dup against a domain that paints its OWN empty block (screen-kit emptyBlock is
       // gated on the domain's top-level `noEmpty`): only one empty state ever shows.
       noEmptySource: !sourceEmpty || s.noEmpty === false,
@@ -330,7 +337,11 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     };
     actions.refresh = (_s, arg) => {
       stashCopy(arg); syncSaved();
-      return backend.controller.query(criteria()).then(() => undefined);
+      // Reconnect refreshes the currently visible result. Rebuild every page the
+      // user had already opened, using fresh cursors, before replacing the snapshot.
+      return (backend.readLifecycle
+        ? backend.controller.query(criteria(), true, true)
+        : backend.controller.query(criteria())).then(() => undefined);
     };
     actions.loadMore = () => backend.controller.loadMore().then(() => undefined);
     actions.retry = actions.collectionRetry = () => backend.controller.retry().then(() => undefined);
@@ -344,7 +355,10 @@ export function decorateCollection(name: string, def: { state: State; actions?:
     const retry = actions.refresh ?? actions.load;
     if (retry) actions.collectionRetry = retry;
   }
-  return { state: derive(def.state), actions };
+  return { state: derive(def.state), actions,
+    ...(requestedReadLifecycle || backend?.readLifecycle ? { readPresentation: derive } : {}),
+    ...(requestedReadLifecycle ? { readLifecycle: requestedReadLifecycle }
+      : backend?.readLifecycle && runtime?.input?.__himiOwnerPreview !== 'sample' ? { readLifecycle: { refreshAction: 'refresh', statusPath: 'readStatus' } } : {}) };
 }
 
 /** Domain-owned page source with shared query controls. Publishing uses a normal
@@ -357,6 +371,8 @@ export function defineBackendCollection<S extends object, Row extends object>(na
   onlineWriteMessageFields?: readonly string[];
   /** Revalidate already opened pages on navigation return; explicit refresh resets. */
   restorePagesOnLoad?: boolean;
+  /** Opt this shared list into the read status and reconnect lifecycle. */
+  readLifecycle?: boolean;
   /** The load action's argument (onAppear params beyond `copy`), before the query runs — for a
    *  domain setting that rides the descriptor, e.g. My Bookings' `weeklyGoal`. */
   onLoad?(arg: unknown): CollectionCriteriaReset | void;
@@ -367,12 +383,16 @@ export function defineBackendCollection<S extends object, Row extends object>(na
   actions?: Record<string, (state: S, ...args: unknown[]) => S | undefined | Promise<S | undefined>>;
 }) {
   let publish: (() => unknown) | undefined;
-  const controller = createCollectionQuery(options.source, () => { publish?.(); });
+  const controller = createCollectionQuery({ ...options.source,
+    // Access-denial clearing belongs to the opt-in read lifecycle. Keep the legacy
+    // collection contract unchanged for templates that have not adopted it.
+    ...(options.readLifecycle ? { clearOnError: error => /HTTP (401|403)\b|forbidden|principal.changed|identity.changed/i.test(String(error)) || options.source.clearOnError?.(error) === true } : {}) }, () => { publish?.(); });
   const definition = decorateCollection(name, { state: options.state as State, actions: options.actions as Record<string, Reducer> | undefined }, options.saving, {
     restorePagesOnLoad: options.restorePagesOnLoad,
+    readLifecycle: options.readLifecycle,
     onLoad: options.onLoad,
     controller: controller as unknown as BackendCollection['controller'],
-    apply: (state, page) => options.apply(state as S, page as unknown as CollectionQueryState<Row>) as State,
+    apply: (state, page) => ({ ...options.apply(state as S, page as unknown as CollectionQueryState<Row>), ...(options.readLifecycle ? { readStatus: page.read } : {}) }) as State,
   });
   const registerService = options.onlineWrites ? withOnlineWrites(options.register ?? register, ['confirmCancel', 'confirmOperation', 'retryOperation', 'commitWrite'], { messageFields: options.onlineWriteMessageFields ?? ['actionMessage'] }) : (options.register ?? register);
   const handle = registerService(name, definition);

package/templates/branded-lite/tier5-src/_shared/iap-presentation.ts

@@ -103,6 +103,8 @@ export function withIapPresentation<S extends object>(options: {
         // scopeLanded is the completion of the active load, not a stale load result. It
         // must publish even if another overlapping onAppear load advanced contentVersion.
         if (!next || (content && action !== "scopeLanded" && version !== contentVersion)) return undefined;
+        // A committed read projection supersedes older load results still carrying a skeleton.
+        if (action === "readChanged" && definition.readLifecycle) contentVersion++;
         if (content) {
           options.onContent?.(next);
           const nextItems = options.items(next);
@@ -130,9 +132,11 @@ export function withIapPresentation<S extends object>(options: {
       };
       try {
         const next = reduce(state, ...args);
-        // Keep synchronous sidecars synchronous. Adding an await lets their old
-        // catalog snapshot commit after a newer asynchronous refresh.
-        if (content || (next && typeof (next as Promise<S | undefined>).then === "function")) {
+        // A cached read projection must commit before another onAppear can consume it.
+        // Other content actions retain their scheduling: shop filters and panels can
+        // change while a load is pending, and their existing completion order matters.
+        const synchronousReadProjection = action === "readChanged" && !!definition.readLifecycle;
+        if ((content && !synchronousReadProjection) || (next && typeof (next as Promise<S | undefined>).then === "function")) {
           return (async () => {
             try { return presentResult(await next); }
             finally { finished(); }

package/templates/branded-lite/tier5-src/_shared/read-service.ts

@@ -0,0 +1,255 @@
+import { stashCopy } from './himi-copy.js';
+const offlineReadsEnabled = true;
+import { isNotFound } from './owner-load-error.js';
+import { defineService as register, createReadController, initialReadStatus, type ServiceDefinition, type ReadMetadata, type ReadStatus } from '@himalaya/state';
+
+export interface ReadOptions {
+  cache: 'only-if-cached' | 'reload';
+  onCacheResult(metadata: ReadMetadata): void;
+}
+/** Passed explicitly down the loader's call graph; never a process-global cache mode. */
+export function readOptions(arg: unknown): ReadOptions | undefined {
+  return (arg as { __himiRead?: ReadOptions } | undefined)?.__himiRead;
+}
+
+/** Explicit request context for loaders with their own presentation state (e.g. IAP). */
+export async function policyRead<T>(cache: ReadOptions['cache'], load: (options: ReadOptions) => Promise<T>, localResult?: (data: T) => boolean) {
+  let metadata: ReadMetadata | undefined;
+  const data = await load({ cache, onCacheResult(value) {
+    metadata = metadata ? { ...value, source: metadata.source === 'cache' || value.source === 'cache' ? 'cache' : 'network',
+      cacheable: metadata.cacheable && value.cacheable,
+      fetchedAt: Math.min(metadata.fetchedAt, value.fetchedAt),
+      expiresAt: Math.min(metadata.expiresAt ?? 0, value.expiresAt ?? 0) } : value;
+  } });
+  if (!metadata && localResult?.(data)) metadata = { source: 'local', cacheable: false, fetchedAt: Date.now() };
+  if (!metadata) throw new Error('Read loader did not provide response provenance');
+  return { data, metadata };
+}
+
+type State = Record<string, unknown>;
+type Action = (state: State, arg?: unknown) => State | undefined | Promise<State | undefined>;
+type ReadFailure = Error & { userMessage?: string; signInRequired?: boolean };
+// A record Wix answers 404 for is gone (a delete whose reply was lost): its retained snapshot must
+// not outlive it. Unlike `denied`, it leaves drafts and local controls alone.
+const gone = (error: unknown) => isNotFound(error);
+const denied = (error: unknown) => /HTTP (401|403)\b|forbidden|principal.changed|identity.changed|member access changed/i.test(String(error));
+
+/** Adapts a read-only load reducer. Callers forward readOptions(arg) to every
+ * primary SDK read and let errors reject. Other actions remain ordinary reducers.
+ * The retained snapshot is in memory; persistence belongs exclusively to the
+ * policy-controlled Wix cache, never to generic worker hydration or local-db rows.
+ */
+export function withReadLifecycle(registerService: typeof register = register, loadAction = 'load', options: {
+  errorMessage?(error: unknown): string;
+  /** Only an authored create form or guest shell; never a server-derived fallback. */
+  localResult?(state: State): boolean;
+  /** Additional host-owned scope when a read explicitly addresses another site. */
+  scopeKey?(): string;
+  /** Clear module-owned read sidecars on identity loss, access denial, or disposal. */
+  onInvalidate?(): void;
+  /** Editable fields survive recovery once loaded, and edits during an initial read. */
+  preserveFields?: readonly string[];
+  unavailable?(state: State, status: ReadStatus): State;
+  /** Authored source content only; never return a network mirror or demo fallback here. */
+  authoredFallback?(state: State, status: ReadStatus): State | undefined;
+} = {}): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => {
+    if ((globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input?.__himiOwnerPreview === 'sample') return registerService(name, definition);
+    const load = definition.actions?.[loadAction] as Action | undefined;
+    if (!load || definition.readLifecycle) return registerService(name, definition);
+    let args: Record<string, unknown> = {}, key = '', page: State | undefined, read = initialReadStatus();
+    let replacePage = false;
+    let activeLoad: { promise: Promise<void>; revision: number } | undefined;
+    let startedState: State | undefined;
+    let hadSnapshot = false, accessRevoked = false, accessNeedsSignIn = false;
+    const localResult = options.localResult ?? (value => value.notFound === true);
+    let projectedState: State | undefined;
+    const editedFields = new Set<string>();
+    let service: { getState(): State; readChanged(): Promise<unknown> };
+    const project = (state: State): State => {
+      for (const field of options.preserveFields ?? []) {
+        if (projectedState && JSON.stringify(state[field]) !== JSON.stringify(projectedState[field])) editedFields.add(field);
+      }
+      const value: State = { ...state, ...(replacePage && page ? page : !read.hasSnapshot ? definition.state : {}), readStatus: read };
+      replacePage = false;
+      if (accessRevoked) for (const field of options.preserveFields ?? []) {
+        if (Object.prototype.hasOwnProperty.call(definition.state, field)) value[field] = definition.state[field];
+        else delete value[field];
+      }
+      // Drafts and local controls survive both missing snapshots and pending reads.
+      for (const field of accessRevoked ? [] : Object.keys(state)) {
+        if (options.preserveFields?.includes(field) && (hadSnapshot || editedFields.has(field))) value[field] = state[field];
+        if (/Draft$|^draft$|^quantity$|^selection$|^selected|^expandedIds$|^searchQuery$|^query$|^filter$|^sort$/.test(field) &&
+          (!read.hasSnapshot || (startedState && JSON.stringify(state[field]) !== JSON.stringify(startedState[field])))) value[field] = state[field];
+      }
+      if (!read.hasSnapshot) {
+        const authored = options.authoredFallback?.(value, read);
+        if (authored) return projectedState = { ...authored, readStatus: { ...read, hasLocalContent: true } };
+        const message = read.offline ? 'This content isn’t available offline. Connect to load it.' : read.error;
+        const unavailable = { ...value, status: read.refreshing ? 'loading' : 'error', isLoading: read.refreshing,
+          notLoading: !read.refreshing, busy: !read.refreshing, hideContent: true, errored: !read.refreshing, isErrored: !read.refreshing,
+          notErrored: read.refreshing, found: false, noEntity: true, hideNotFound: true, hideLoading: !read.refreshing, hideLoadError: read.refreshing, error: message, errorText: message, emptyText: message, noEmpty: true };
+        if (accessRevoked) Object.assign(unavailable, { readDenied: true, signInRequired: accessNeedsSignIn, noSignIn: !accessNeedsSignIn });
+        return projectedState = options.unavailable?.(unavailable, read) ?? unavailable;
+      }
+      return projectedState = definition.readPresentation?.(value) ?? value;
+    };
+    const perform = async (cache: ReadOptions['cache'], requestKey: string) => {
+      const requestArgs = requestKey ? JSON.parse(requestKey) as Record<string, unknown> : {};
+      return policyRead(cache, async readContext => {
+      const input = { ...(service?.getState() ?? definition.state), __himiRead: readContext } as State;
+      // Unavailable-state flags added by this adapter are presentation, not a failed
+      // domain read. A reducer that spreads its input must not inherit those flags
+      // and have its successful cached/local result rejected as another failure.
+      for (const field of ['errored', 'isErrored']) {
+        if (!Object.prototype.hasOwnProperty.call(definition.state, field)) delete input[field];
+      }
+      // An unsaved create form is authored local content. Its no-op loader must
+      // receive its declared status, not the adapter's temporary unavailable state.
+      if (!read.hasSnapshot && options.localResult?.(input)) input.status = definition.state.status;
+      const data = await load(input, { ...requestArgs, __himiRead: readContext });
+      if (!data || data.status === 'error' || data.errored === true || data.isErrored === true) {
+        const unauthorized = data?.signInRequired === true || /HTTP 401|unauthori[sz]ed|sign[\s-]?in/i.test(String(data?.error || data?.errorText || ''));
+        const failure = new Error(unauthorized ? 'HTTP 401 unauthorized' : data?.readDenied ? 'HTTP 403 forbidden' : 'Read failed') as ReadFailure;
+        failure.signInRequired = data?.signInRequired === true;
+        const userMessage = data?.error || data?.errorText || data?.emptyText;
+        if (typeof userMessage === 'string' && userMessage.trim()) failure.userMessage = userMessage.trim();
+        throw failure;
+      }
+      delete data.__himiRead;
+      return data;
+      }, localResult);
+    };
+    const controller = createReadController<State>({
+      allowLocal: true, cached: key => perform('only-if-cached', key), fetch: key => perform('reload', key), clearOnError(error) {
+        accessRevoked = denied(error);
+        accessNeedsSignIn = (error as ReadFailure | null)?.signInRequired === true || /HTTP 401|unauthori[sz]ed|sign[\s-]?in/i.test(String(error));
+        const clear = accessRevoked || gone(error);
+        if (clear) options.onInvalidate?.();
+        return clear;
+      }, errorMessage(error) {
+        return (error as ReadFailure | null)?.userMessage || options.errorMessage?.(error) || (accessNeedsSignIn ? 'Sign in to view this content.' : '') || '';
+      },
+      publish(data, status) {
+        // A failed revalidation republishes the controller's retained snapshot. The worker
+        // state can contain newer local changes (for example, another fetched page or a
+        // selected row), so do not replace that state with the older controller page on a
+        // stale/error publication. A first cached paint and a successful refresh still
+        // replace the visible read data.
+        replacePage = status.hasSnapshot && data !== undefined
+          && (!page || (!status.refreshing && !status.stale && !status.error));
+        page = data;
+        read = status;
+        void service?.readChanged();
+      },
+    });
+    const host = (globalThis as { himalaya?: { __subscribeReadLifecycle?(listener: (signal: string) => void): () => void } }).himalaya;
+    let unsubscribeAdapter: (() => void) | undefined;
+    unsubscribeAdapter = host?.__subscribeReadLifecycle?.(signal => {
+      if (signal === 'dispose') { options.onInvalidate?.(); unsubscribeAdapter?.(); return; }
+      if (signal !== 'invalidate') return;
+      options.onInvalidate?.();
+      // Identity invalidation clears the controller's private snapshot, so the
+      // adapter must also forget that its form fields came from a prior user.
+      // Otherwise project() can preserve those fields while the host clears the
+      // shared read state.
+      hadSnapshot = false;
+      accessRevoked = true;
+      accessNeedsSignIn = false;
+      editedFields.clear();
+      page = undefined;
+      read = initialReadStatus();
+      replacePage = true;
+      void service?.readChanged();
+    });
+    const refresh: Action = async (_state, arg) => {
+      stashCopy(arg);
+      if (arg && typeof arg === 'object') {
+        args = { ...arg as Record<string, unknown> };
+        // Localized copy is presentation, not a different backend query.
+        delete args.copy;
+      }
+      const next = JSON.stringify({ ...((globalThis as { himalaya?: { input?: Record<string, unknown> } }).himalaya?.input ?? {}), ...args, ...(options.scopeKey ? { __readScope: options.scopeKey() } : {}) });
+      // Coalesce through the final state projection, not only the controller's
+      // network task. A module-scope load() and the host's boot/onAppear load()
+      // commonly join the same request; returning when the fetch settles lets the
+      // host snapshot the worker before the first caller's readChanged() publishes.
+      if (key === next && activeLoad && activeLoad.revision === controller.getRevision()) {
+        await activeLoad.promise;
+        await service?.readChanged();
+        return service?.getState();
+      }
+      hadSnapshot = read.hasSnapshot && key === next;
+      key = next;
+      startedState = service?.getState() ?? definition.state;
+      projectedState = startedState; editedFields.clear(); accessRevoked = false; accessNeedsSignIn = false;
+      const load = controller.load(key);
+      const revision = controller.getRevision();
+      const task = (async () => {
+        await load;
+        // Controller publications project through this service action. Await its final
+        // projection before resolving load/retry so hosts that serialize worker actions
+        // cannot render the pre-read state after the request has completed.
+        await service?.readChanged();
+      })();
+      const active = { promise: task, revision };
+      activeLoad = active;
+      try {
+        await task;
+      } finally { if (activeLoad === active) activeLoad = undefined; }
+      return await service?.getState();
+    };
+    service = registerService(name, { ...definition, readLifecycle: { refreshAction: 'refreshRead', statusPath: 'readStatus' },
+      state: { ...definition.state, readStatus: read },
+      actions: { ...definition.actions, ...(loadAction !== "refresh" && definition.actions?.refresh ? { refresh: () => controller.refresh().then(() => undefined) } : {}), [loadAction]: refresh, retry: () => controller.refresh().then(() => undefined),
+        refreshRead: refresh, readChanged: project },
+    });
+    return service;
+  }) as typeof register;
+}
+
+// Generic services keep their existing behavior. A `load` action is not proof
+// that it is a safe, cache-eligible read: local device state and writes often use
+// that name too. Shared read helpers and opted-in screens register through
+// withReadLifecycle explicitly.
+export const defineService: typeof register = register;
+/** Safe opt-in for a service whose load action is a cache-eligible read. */
+export const readService: typeof register = withReadLifecycle();
+
+
+/** Raw read escape hatch for an endpoint without a generated SDK binding. */
+export async function rawRead<T>(method: string, path: string, body?: unknown, options?: ReadOptions): Promise<T> {
+  const api = (globalThis as any).himalaya?.wixApi;
+  if (!api) throw new Error('Wix bridge unavailable');
+  if (!options) return api.call(method, path, body) as Promise<T>;
+  if (!api.read) throw new Error('READ_LIFECYCLE_UNSUPPORTED');
+  const result = await api.read(method, path, body, undefined, { cache: options.cache });
+  options.onCacheResult(result.cache);
+  return result.data as T;
+}
+
+/** Editor recovery refreshes its read eligibility without replacing an open draft
+ * or its concurrency revision. Field values remain owned by the form until the
+ * user explicitly submits or reopens it. Only a new, unsaved form is local data. */
+export function withFormReadLifecycle(registerService: typeof register = register): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => withReadLifecycle(registerService, 'load', {
+    preserveFields: ['title', 'name', 'price', 'sku', 'visible', 'revision', 'category',
+      'description', 'originalDescription', 'descriptionMode', 'descriptionJson', 'descriptionDirty', 'descriptionEdits',
+      'when', 'location', 'excerpt', 'body', 'richContent', 'bodyJson', 'bodyDirty', 'bodyEdits',
+      'detailsOpen', 'coverUrl', 'originalCoverUrl', 'coverPreview', 'isFeatured',
+      'question', 'answer', 'answerFormat', 'answerMode', 'answerJson', 'answerDirty', 'answerEdits', 'categoryId', 'statusValue'],
+    localResult: value => value.mode === 'create' && !value.id,
+  })(name, definition)) as typeof register;
+}
+
+/** Server-derived state is never a generic worker snapshot; explicit drafts may persist. */
+export function withReadPersistence(registerService: typeof register, draftFields: readonly string[] = []): typeof register {
+  if (!offlineReadsEnabled) return registerService;
+  return ((name: string, definition: ServiceDefinition<State>) => registerService(name, {
+    ...definition,
+    notPersisted: [...new Set([...(definition.notPersisted ?? []),
+      ...Object.keys(definition.state).filter(key => !draftFields.includes(key))])],
+  })) as typeof register;
+}

package/templates/branded-lite/tier5-src/himi-branded-lite-home/index.ts

@@ -250,7 +250,7 @@ interface State {
   hideFeaturedSkeleton: boolean;
   welcome: string;
   refreshedAt: string;
-  /** The resolved home layout preset (RFC 0045 FragmentSlot discriminator).
+  /** The resolved home layout preset (shared slot discriminator).
    *  Plain string, never a proto enum — a `$service:` casePath decodes it as a
    *  JSON string and unknown values fall through to the shipped defaultCase. */
   effectiveLayout: string;

package/templates/branded-lite/tier5-src/himi-branded-lite-orders/index.ts

@@ -161,6 +161,9 @@ function derive(state: State): State {
   });
   return {
     ...state,
+    nextCursor: state.nextCursor ?? "",
+    filterOptions: state.filterOptions ?? [{ id: "all", label: copyParam("collection.all", "All"), selected: true },
+      ...Object.keys(FULFILLMENT).map(label => ({ id: `value:${label}`, label: copyParam(`collection.filter.${label}`, label), selected: false }))],
     displayRows: rows.map((row, index, rows) => {
       // Older owned cache rows retain their original date in meta. Group only
       // adjacent days so pagination and an explicit backend sort remain authoritative.