@wix/himalaya-cli 0.1451.0 → 0.1453.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/webview.mjs

@@ -1,25 +1,15 @@
-// ../../core/sdk/webview/src/index.ts
-function runtime() {
-  const himalaya = globalThis.himalaya;
-  if (!himalaya?.webview) {
-    throw new Error(
-      '@himalaya/webview: called outside a Himalaya runtime, or the host did not install the webview bridge. This binding must run inside a worker-backed webview screen (Tier 5 + webview renderer) with the "webview" capability declared.'
-    );
-  }
-  return himalaya.webview;
-}
-function postToPage(msg) {
-  runtime().postToPage(msg);
-}
-function onPageMessage(cb) {
-  runtime().onPageMessage(cb);
-}
+// ../../core/sdk/webview/src/dispatcher.ts
 var PAGE_HANDSHAKE_CAPABILITY = "himalaya";
 var PAGE_HANDSHAKE_METHOD = "capabilities";
+var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["call", "on", "probe", "version", "then", "constructor", "general"]);
+var UNREACHABLE_SEGMENTS = /* @__PURE__ */ new Set(["then", "toString", "valueOf"]);
+var NAMESPACE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var METHOD_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,63}(?:\.[A-Za-z][A-Za-z0-9_]{0,63}){0,3}$/;
+var ID_PATTERN = /^[A-Za-z0-9-]{1,96}$/;
 function pageRequest(value) {
   if (!value || typeof value !== "object") return null;
   const request = value;
-  if (request.v !== 1 || typeof request.id !== "string" || !/^[A-Za-z0-9-]{1,96}$/.test(request.id) || typeof request.capability !== "string" || !/^[a-z][a-z0-9_]{0,63}$/.test(request.capability) || typeof request.method !== "string" || !/^[A-Za-z][A-Za-z0-9_]{0,63}(?:\.[A-Za-z][A-Za-z0-9_]{0,63}){0,3}$/.test(request.method) || !Array.isArray(request.args) || request.args.length > 12) return null;
+  if (request.v !== 1 || typeof request.id !== "string" || !ID_PATTERN.test(request.id) || typeof request.capability !== "string" || !NAMESPACE_PATTERN.test(request.capability) || typeof request.method !== "string" || !METHOD_PATTERN.test(request.method) || !Array.isArray(request.args) || request.args.length > 12) return null;
   return request;
 }
 function pageError(value) {
@@ -30,52 +20,518 @@ function pageError(value) {
     ...typeof code === "string" && code ? { code } : {}
   };
 }
-function exposeCapabilitiesToPage(capabilities) {
-  if (Object.prototype.hasOwnProperty.call(capabilities, PAGE_HANDSHAKE_CAPABILITY)) {
-    throw new Error(`"${PAGE_HANDSHAKE_CAPABILITY}" is reserved for the page handshake and cannot be exposed`);
-  }
-  const allowed = new Map(
-    Object.entries(capabilities).map(([id, entry]) => [id, {
-      module: entry.module,
-      methods: new Set(entry.methods)
-    }])
-  );
-  const manifest = Object.fromEntries(
-    [...allowed].map(([id, entry]) => [id, [...entry.methods].sort()])
-  );
-  onPageMessage((message) => {
-    const request = pageRequest(message);
-    if (!request) return;
-    if (request.capability === PAGE_HANDSHAKE_CAPABILITY) {
-      if (request.method === PAGE_HANDSHAKE_METHOD) {
-        postToPage({ v: 1, id: request.id, ok: true, result: { v: 1, capabilities: manifest } });
+var key = (instanceId, id) => `${instanceId}\0${id}`;
+var instanceOf = (value) => typeof value === "string" ? value : "";
+function createPageDispatcher(runtime2) {
+  let installed = false;
+  let lifecycleInstalled = false;
+  let raw = null;
+  const exposed = /* @__PURE__ */ new Map();
+  const namespaces = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const lingering = /* @__PURE__ */ new Map();
+  let calling = null;
+  const crashed = /* @__PURE__ */ new Set();
+  const streams = /* @__PURE__ */ new Map();
+  const handles = /* @__PURE__ */ new WeakMap();
+  const live = /* @__PURE__ */ new Set();
+  const inactive = /* @__PURE__ */ new Set();
+  const gone = /* @__PURE__ */ new Set();
+  const lifecycleSubscribers = /* @__PURE__ */ new Set();
+  const consoleSubscribers = /* @__PURE__ */ new Set();
+  const instanceAware = () => typeof runtime2.onPageLifecycle === "function";
+  const register = runtime2.onPageMessage;
+  try {
+    runtime2.onPageMessage = (cb) => {
+      raw = typeof cb === "function" ? (msg, instanceId) => cb(msg, instanceId) : null;
+      if (!installed) register.call(runtime2, cb);
+    };
+  } catch {
+  }
+  function assertFree(name) {
+    if (exposed.has(name)) throw new Error(`page capability "${name}" is already exposed`);
+    if (namespaces.has(name)) throw new Error(`page namespace "${name}" is already registered`);
+  }
+  function install() {
+    if (!installed) {
+      installed = true;
+      register.call(runtime2, (msg, instanceId) => onPage(msg, instanceOf(instanceId)));
+    }
+    if (!lifecycleInstalled && instanceAware()) {
+      lifecycleInstalled = true;
+      runtime2.onPageLifecycle((envelope, instanceId) => onLifecycle(envelope, instanceId));
+    }
+  }
+  function setRawHandler(cb) {
+    raw = cb;
+    install();
+  }
+  function assertReachable(name, kind) {
+    if (typeof name !== "string" || !NAMESPACE_PATTERN.test(name)) {
+      throw new Error(`page ${kind} ${JSON.stringify(name)} must match ${NAMESPACE_PATTERN}`);
+    }
+    if (RESERVED_NAMESPACES.has(name)) {
+      throw new Error(`page ${kind} "${name}" is reserved: the page's himalaya.${name} is not a namespace`);
+    }
+  }
+  function expose(capabilities) {
+    for (const id of Object.keys(capabilities)) {
+      if (id === PAGE_HANDSHAKE_CAPABILITY) {
+        throw new Error(`"${PAGE_HANDSHAKE_CAPABILITY}" is reserved for the page handshake and cannot be exposed`);
       }
+      assertReachable(id, "capability");
+      assertFree(id);
+    }
+    for (const [id, entry] of Object.entries(capabilities)) {
+      exposed.set(id, { module: entry.module, methods: new Set(entry.methods) });
+    }
+    install();
+  }
+  function addNamespace(namespace, handlers) {
+    if (namespace === PAGE_HANDSHAKE_CAPABILITY) {
+      throw new Error(`"${PAGE_HANDSHAKE_CAPABILITY}" is reserved for the page handshake and cannot be a namespace`);
+    }
+    assertReachable(namespace, "namespace");
+    assertFree(namespace);
+    const methods = /* @__PURE__ */ new Map();
+    for (const [method, handler] of Object.entries(handlers ?? {})) {
+      if (!METHOD_PATTERN.test(method)) {
+        throw new Error(`page method ${JSON.stringify(`${namespace}.${method}`)} must match ${METHOD_PATTERN}`);
+      }
+      const segments = method.split(".");
+      if (segments[0] === "on" || segments.some((segment) => UNREACHABLE_SEGMENTS.has(segment))) {
+        throw new Error(`page method ${JSON.stringify(`${namespace}.${method}`)} is reserved: the page proxy cannot call it`);
+      }
+      if (typeof handler !== "function") throw new Error(`page handler ${namespace}.${method} is not a function`);
+      methods.set(method, handler);
+    }
+    namespaces.set(namespace, methods);
+    install();
+  }
+  function subscribeLifecycle(cb) {
+    lifecycleSubscribers.add(cb);
+    install();
+    return () => {
+      lifecycleSubscribers.delete(cb);
+    };
+  }
+  function subscribeConsole(cb) {
+    consoleSubscribers.add(cb);
+    install();
+    return () => {
+      consoleSubscribers.delete(cb);
+    };
+  }
+  function post(instanceId, msg) {
+    if (instanceAware()) runtime2.postToPage(msg, instanceId);
+    else if (instanceId === "") runtime2.postToPage(msg);
+  }
+  function emit(target, event, data) {
+    install();
+    const dot = typeof event === "string" ? event.indexOf(".") : -1;
+    const ns = dot > 0 ? event.slice(0, dot) : "";
+    const ev = dot > 0 ? event.slice(dot + 1) : "";
+    if (!NAMESPACE_PATTERN.test(ns) || !ev) {
+      throw new Error(`emitToPage event ${JSON.stringify(event)} must be "<namespace>.<event>"`);
+    }
+    const envelope = { v: 1, ev, ns, data };
+    if (target === "*") {
+      const targets = instanceAware() ? live : /* @__PURE__ */ new Set([...live, ""]);
+      for (const instanceId of [...targets]) post(instanceId, envelope);
+    } else {
+      post(target, envelope);
+    }
+  }
+  function openStream(instanceId, requestId) {
+    const k = key(instanceId, requestId);
+    let pending;
+    let ambiguous = false;
+    if (calling?.k === k) pending = calling.pending;
+    else {
+      pending = inFlight.get(k);
+      ambiguous = (lingering.get(k)?.size ?? 0) > 0;
+    }
+    const existing = streams.get(k);
+    if (existing && !ambiguous && pending && existing.owner === pending) return existing.handle;
+    if (pending?.abandoned || ambiguous || pending && existing) {
+      const dead = {
+        owner: null,
+        instanceId,
+        sid: requestId,
+        buffer: null,
+        closed: true,
+        aborted: true,
+        cancelled: [],
+        handle: void 0
+      };
+      dead.handle = {
+        next: () => {
+        },
+        end: () => {
+        },
+        error: () => {
+        },
+        onCancel: (cb) => {
+          if (typeof cb === "function") runCancel(cb);
+        },
+        get closed() {
+          return true;
+        }
+      };
+      handles.set(dead.handle, dead);
+      return dead.handle;
+    }
+    if (!pending) {
+      throw new Error(`openPageStream: no request ${JSON.stringify(requestId)} is awaiting an answer on instance ${JSON.stringify(instanceId)}`);
+    }
+    const state = {
+      owner: pending,
+      instanceId,
+      sid: requestId,
+      buffer: [],
+      closed: false,
+      aborted: false,
+      cancelled: [],
+      handle: void 0
+    };
+    const send = (envelope, last) => {
+      if (state.closed) return;
+      if (last) state.closed = true;
+      if (state.buffer) state.buffer.push(envelope);
+      else post(instanceId, envelope);
+      if (last && !state.buffer && streams.get(k) === state) streams.delete(k);
+    };
+    state.handle = {
+      // JSON drops an `undefined` member, and a page reads `{ v, sid }` alone as no chunk at all.
+      next: (data) => send({ v: 1, sid: state.sid, chunk: data === void 0 ? null : data }, false),
+      end: () => send({ v: 1, sid: state.sid, end: true }, true),
+      error: (e) => send({ v: 1, sid: state.sid, error: pageError(e) }, true),
+      onCancel: (cb) => {
+        if (typeof cb !== "function") return;
+        if (state.aborted) runCancel(cb);
+        else state.cancelled.push(cb);
+      },
+      get closed() {
+        return state.closed;
+      }
+    };
+    streams.set(k, state);
+    handles.set(state.handle, state);
+    return state.handle;
+  }
+  function onPage(msg, instanceId) {
+    const sys = msg && typeof msg === "object" && msg.v === 1 ? msg.sys : void 0;
+    if (sys === "cancel") return cancel(instanceId, msg.sid);
+    if (sys === "console") return forwardConsole(instanceId, msg);
+    const dead = gone.has(instanceId);
+    if (!dead) live.add(instanceId);
+    const request = exposed.size > 0 || namespaces.size > 0 ? pageRequest(msg) : null;
+    if (!request) {
+      raw?.(msg, instanceId);
+      return;
+    }
+    if (!dead) route(request, instanceId, msg);
+  }
+  function route(request, instanceId, message) {
+    const respond = (response) => post(instanceId, { v: 1, id: request.id, ...response });
+    if (request.capability === PAGE_HANDSHAKE_CAPABILITY) {
+      if (request.method === PAGE_HANDSHAKE_METHOD) respond({ ok: true, result: { v: 1, capabilities: manifest() } });
+      return;
+    }
+    const capability = exposed.get(request.capability);
+    if (capability) {
+      const { fn, receiver } = resolvePath(capability.module, request.method);
+      if (!capability.methods.has(request.method) || !fn) return;
+      const pending2 = begin(key(instanceId, request.id));
+      void Promise.resolve().then(() => fn.apply(receiver, request.args)).then(
+        (result) => {
+          if (settle(key(instanceId, request.id), pending2)) respond({ ok: true, result });
+        },
+        (error) => {
+          if (settle(key(instanceId, request.id), pending2)) respond({ ok: false, error: pageError(error) });
+        }
+      );
+      return;
+    }
+    const methods = namespaces.get(request.capability);
+    if (!methods) {
+      raw?.(message, instanceId);
       return;
     }
-    const capability = allowed.get(request.capability);
-    let candidate = capability?.module;
-    let receiver = void 0;
-    for (const segment of request.method.split(".")) {
-      if (!candidate || typeof candidate !== "object" || !Object.prototype.hasOwnProperty.call(candidate, segment)) {
-        candidate = void 0;
+    const handler = methods.get(request.method);
+    if (!handler) {
+      respond({
+        ok: false,
+        error: { message: `Unknown page method: ${request.capability}.${request.method}`, code: "unknown_method" }
+      });
+      return;
+    }
+    const k = key(instanceId, request.id);
+    const pending = begin(k);
+    const ctx = {
+      instanceId,
+      requestId: request.id,
+      get active() {
+        return !inactive.has(instanceId) && !gone.has(instanceId);
+      }
+    };
+    void Promise.resolve().then(() => {
+      calling = { k, pending };
+      try {
+        return handler(request.args, ctx);
+      } finally {
+        calling = null;
+      }
+    }).then(
+      (result) => {
+        const reader = settle(k, pending);
+        const stream = ownStream(k, pending);
+        if (!reader) {
+          if (stream) discard(k, stream);
+          return;
+        }
+        if (stream && result === stream.handle) {
+          respond({ ok: true, stream: true });
+          const buffered = stream.buffer ?? [];
+          stream.buffer = null;
+          for (const envelope of buffered) post(instanceId, envelope);
+          if (stream.closed && streams.get(k) === stream) streams.delete(k);
+          return;
+        }
+        if (stream) discard(k, stream);
+        const returned = result && typeof result === "object" ? handles.get(result) : void 0;
+        if (returned) {
+          respond({
+            ok: false,
+            error: { message: "The page stream was closed before it was returned", code: "stream_closed" }
+          });
+          return;
+        }
+        respond({ ok: true, result });
+      },
+      (error) => {
+        const reader = settle(k, pending);
+        const stream = ownStream(k, pending);
+        if (stream) discard(k, stream);
+        if (reader) respond({ ok: false, error: pageError(error) });
+      }
+    );
+  }
+  function settle(k, pending) {
+    if (inFlight.get(k) === pending) inFlight.delete(k);
+    const left = lingering.get(k);
+    if (left?.delete(pending) && left.size === 0) lingering.delete(k);
+    return !pending.abandoned;
+  }
+  function begin(k) {
+    const previous = inFlight.get(k);
+    if (previous && !previous.abandoned) {
+      abandon(k, previous);
+      const stream = ownStream(k, previous);
+      if (stream) discard(k, stream);
+    }
+    const pending = { abandoned: false };
+    inFlight.set(k, pending);
+    return pending;
+  }
+  function abandon(k, pending) {
+    pending.abandoned = true;
+    let left = lingering.get(k);
+    if (!left) lingering.set(k, left = /* @__PURE__ */ new Set());
+    left.add(pending);
+  }
+  function ownStream(k, pending) {
+    const stream = streams.get(k);
+    return stream?.owner === pending ? stream : void 0;
+  }
+  function manifest() {
+    const out = {};
+    for (const [id, entry] of exposed) out[id] = [...entry.methods].sort();
+    for (const [ns, methods] of namespaces) out[ns] = [...methods.keys()].sort();
+    return Object.fromEntries(Object.entries(out).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+  }
+  function runCancel(cb) {
+    try {
+      cb();
+    } catch {
+    }
+  }
+  function discard(k, stream) {
+    const wasOpen = !stream.closed;
+    stream.closed = true;
+    stream.buffer = null;
+    if (streams.get(k) === stream) streams.delete(k);
+    if (!wasOpen || stream.aborted) return;
+    stream.aborted = true;
+    for (const cb of stream.cancelled.splice(0)) runCancel(cb);
+  }
+  function cancel(instanceId, sid) {
+    if (typeof sid !== "string") return;
+    const k = key(instanceId, sid);
+    const stream = streams.get(k);
+    if (stream) discard(k, stream);
+  }
+  function forwardConsole(instanceId, msg) {
+    const event = {
+      instanceId,
+      level: typeof msg.level === "string" ? msg.level : "log",
+      args: Array.isArray(msg.args) ? msg.args : []
+    };
+    for (const cb of [...consoleSubscribers]) {
+      try {
+        cb(event);
+      } catch {
+      }
+    }
+  }
+  function onLifecycle(rawEnvelope, stamped) {
+    let envelope = rawEnvelope;
+    if (typeof envelope === "string") {
+      try {
+        envelope = JSON.parse(envelope);
+      } catch {
+        return;
+      }
+    }
+    const e = envelope;
+    if (!e || typeof e !== "object" || e.v !== 1 || e.sys !== "lifecycle" || typeof e.state !== "string") return;
+    const instanceId = typeof stamped === "string" ? stamped : instanceOf(e.iid);
+    switch (e.state) {
+      // A document start ends any crash pair: a host that restarts a crashed instance this way
+      // sends no `reloaded` for it, so the next `reloaded` is a boundary of its own.
+      case "mounted":
+        live.add(instanceId);
+        gone.delete(instanceId);
+        crashed.delete(instanceId);
+        break;
+      case "loaded":
+        crashed.delete(instanceId);
+        break;
+      case "active":
+        inactive.delete(instanceId);
+        break;
+      case "inactive":
+        inactive.add(instanceId);
+        break;
+      // A new document: the old one's streams and pending requests have no reader any more.
+      // `crashed` is followed by `reloaded` once the host remounted: one boundary, not two, or the
+      // second sweep would hit the NEW document's first requests.
+      case "crashed":
+        crashed.add(instanceId);
+        endDocument(instanceId);
         break;
+      case "reloaded":
+        if (!crashed.delete(instanceId)) endDocument(instanceId);
+        break;
+      case "unmounted":
+        unmount(instanceId);
+        break;
+    }
+    const event = { instanceId, state: e.state, ..."detail" in e ? { detail: e.detail } : {} };
+    for (const cb of [...lifecycleSubscribers]) {
+      try {
+        cb(event);
+      } catch {
       }
-      receiver = candidate;
-      candidate = candidate[segment];
     }
-    if (!capability || !capability.methods.has(request.method) || typeof candidate !== "function") return;
-    void Promise.resolve().then(() => candidate.apply(receiver, request.args)).then(
-      (result) => postToPage({ v: 1, id: request.id, ok: true, result }),
-      (error) => postToPage({ v: 1, id: request.id, ok: false, error: pageError(error) })
+  }
+  function endDocument(instanceId) {
+    for (const stream of [...streams.values()]) {
+      if (stream.instanceId === instanceId) cancel(instanceId, stream.sid);
+    }
+    const prefix = key(instanceId, "");
+    for (const [k, pending] of inFlight) {
+      if (!k.startsWith(prefix)) continue;
+      abandon(k, pending);
+    }
+  }
+  function unmount(instanceId) {
+    live.delete(instanceId);
+    inactive.delete(instanceId);
+    gone.add(instanceId);
+    crashed.delete(instanceId);
+    endDocument(instanceId);
+  }
+  return {
+    runtime: runtime2,
+    get instanceAware() {
+      return instanceAware();
+    },
+    setRawHandler,
+    expose,
+    addNamespace,
+    subscribeLifecycle,
+    subscribeConsole,
+    post,
+    emit,
+    openStream
+  };
+}
+function resolvePath(module, method) {
+  let candidate = module;
+  let receiver = void 0;
+  for (const segment of method.split(".")) {
+    if (!candidate || typeof candidate !== "object" || !Object.prototype.hasOwnProperty.call(candidate, segment)) {
+      return {};
+    }
+    receiver = candidate;
+    candidate = candidate[segment];
+  }
+  return typeof candidate === "function" ? { fn: candidate, receiver } : {};
+}
+
+// ../../core/sdk/webview/src/index.ts
+function runtime() {
+  const himalaya = globalThis.himalaya;
+  if (!himalaya?.webview) {
+    throw new Error(
+      '@himalaya/webview: called outside a Himalaya runtime, or the host did not install the webview bridge. This binding must run inside a worker-backed webview screen (Tier 5 + webview renderer) with the "webview" capability declared.'
     );
-  });
+  }
+  return himalaya.webview;
+}
+var current;
+function dispatcher() {
+  const rt = runtime();
+  if (current?.runtime !== rt) current = createPageDispatcher(rt);
+  return current;
+}
+if (globalThis.himalaya?.webview) dispatcher();
+function postToPage(msg) {
+  runtime().postToPage(msg);
+}
+function onPageMessage(cb) {
+  dispatcher().setRawHandler(cb);
+}
+function onPageRequest(namespace, handlers) {
+  dispatcher().addNamespace(namespace, handlers);
+}
+function emitToPage(instanceId, event, data) {
+  dispatcher().emit(instanceId, event, data);
+}
+function openPageStream(instanceId, requestId) {
+  return dispatcher().openStream(instanceId, requestId);
+}
+function onPageLifecycle(cb) {
+  return dispatcher().subscribeLifecycle(cb);
+}
+function onPageConsole(cb) {
+  return dispatcher().subscribeConsole(cb);
+}
+function exposeCapabilitiesToPage(capabilities) {
+  dispatcher().expose(capabilities);
 }
 var version = 1;
 export {
   PAGE_HANDSHAKE_CAPABILITY,
   PAGE_HANDSHAKE_METHOD,
+  emitToPage,
   exposeCapabilitiesToPage,
+  onPageConsole,
+  onPageLifecycle,
   onPageMessage,
+  onPageRequest,
+  openPageStream,
   postToPage,
   version
 };

package/guides/designing-himi-screens.md

@@ -337,7 +337,7 @@ to drive them:
 
 | State | Compose with | Notes |
 |---|---|---|
-| **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. |
+| **Loading** | `Skeleton` (shape of the eventual content) or `StatefulSection` / `ActivityIndicator` | Required on every screen that loads data asynchronously, and re-checked on every redesign. Prefer a content-shaped `Skeleton` over a bare spinner — it previews the layout. The descriptor renders against the state-skeleton, then repaints as worker state lands. See [Loading states](#loading-states-part-of-the-design) below. |
 | **Empty** | `EmptyState` (`title`, optional `icon` / `subtitle`) **plus a directive action** (`action` + `actionLabel`) | An empty screen is an invitation to act, not a dead end. Give it the next step, for example `"actionLabel": "Add your first item"`. Use `EmptyState` for **every** empty state, so all empty states in the app have the same layout and style. See [Empty states](#empty-states-one-component-one-layout) below. |
 | **Error** | `Banner` (or inline) **with a retry action** | Say what failed and offer recovery; never a blank screen or a raw error string. |
 | **Loaded** | the real content | The one everyone remembers to build. |
@@ -347,6 +347,38 @@ Bind visibility to worker state with `hidden_path` (`$service:…`/`$item.` data
 components precisely so states are first-class — use them. (Reproducing an existing app? Enumerate
 every state the *original* shows; the same discipline applies to net-new screens.)
 
+### Loading states: part of the design
+
+A screen that loads data asynchronously ships its loading state with it. The loading state is
+part of the screen's design, not an implementation detail to fill in later: it is the first thing
+the user sees, and on a slow network it is the whole screen.
+
+- **New screens.** Every new screen that waits for data — a worker fetch, a Wix call, a
+  `$service:` value that arrives after the first paint — has a designed loading state.
+- **Redesigns.** When you change the layout of an existing data screen, review its loading state
+  in the same change. Update it when its **structure** (sections added, removed or reordered),
+  **hierarchy** (a new hero, a different first row) or **content** (a list became a grid, a row
+  gained an image) no longer matches the redesigned screen. A loader that still shows the old
+  layout makes the screen jump when the data lands. Compare the two frames:
+  `himi render <screenId> --no-mocks` draws the initial frame, which is the loading state, and
+  `himi render <screenId> --state '{"<svc>":{…}}'` draws the loaded one. (A plain `himi render`
+  loads the app's recorded data by default when it has any, so it shows the loaded screen, not the
+  loader.)
+- **Prefer a content-shaped `Skeleton`** when you know the loaded layout: the same sections, in
+  the same order, at about the same sizes (`width`, `height`, `cornerRadius`, and `count` for
+  repeated rows). It previews the layout, so nothing moves when the data arrives.
+- **Use another existing loading component when it fits the behavior better.** `StatefulSection`
+  suits a section that loads on its own; it can skip the skeleton for a load that settles quickly
+  (`loadingGraceMs`) and holds a painted skeleton long enough not to flicker (`loadingFloorMs`).
+  `ActivityIndicator` suits a wait whose layout is not known in advance, or a short local wait
+  such as a pull-to-refresh or a button's own pending state.
+- **Loading is its own state — not empty, not error.** Do not show the empty state while the data
+  is still loading, and do not leave the skeleton up after a load has failed. Each state has its own
+  node, driven by its own worker flag (see `himi docs recipe-four-state`).
+- **Static screens have no loading state.** A screen whose content is already in the descriptor —
+  a settings list, an about page, a form with nothing to prefill — renders at once. Do not add a
+  skeleton to it.
+
 ### Empty states: one component, one layout
 
 `EmptyState` draws one standard layout on iOS, Android, macOS and web. Do not build an empty
@@ -451,6 +483,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 
 - [ ] **One** primary action, on the one `accentPrimary` surface?
 - [ ] All four states designed — loading / empty / error / loaded (empty & error have an action)?
+- [ ] Loading state matches the loaded layout (a content-shaped `Skeleton` where the layout is known)? For a redesign, was the existing loading state reviewed against the new layout? A static screen has none?
 - [ ] Every value a token — zero literal hex / off-scale spacing / invented type sizes?
 - [ ] Is every user-facing string routed through a copy key with a sensible fallback (`copyOf(key, fallback)` backed by your own `COPY` map; worker strings via `onAppear` params) — none baked directly into the descriptor?
 - [ ] When a business book exists, do those fallbacks use the site's OWN words (`book.copy`) rather than stock phrases — and in `book.copy.language`?

package/guides/index.json

@@ -24,6 +24,7 @@
     "To SELL an App Store item, a screen composes `createIapCommerce` from `@himalaya/iap-checkout` once per worker (its catalog pricing plus the shared checkout, with the vertical's order adapter) and binds its Get access action with `commerce.purchaseFields`: the order, Apple's sheet, proof delivery, finishing and the access read all happen inside it. Never call StoreKit (`purchaseForVerification`), `finishTransaction` or the payment client from a worker, never fall back to Wix checkout for an App Store item, and show access only when it reports `accessReady`. Purchasing stays unavailable until Wix provides its routes and mapping.",
     "Keep structure descriptor-authored: use FragmentSlot for enumerable variants and bound list/grid templates for repetition. Use WorkerSubtree only for runtime-unknowable structure, with an explicit screen allowlist, policy budgets, and shipped fallback.",
     "Bindings ($service:<svc>.<path>, $item.<field>, $flag:<key>) are plain strings in ANY prop — INCLUDING Modifiers token refs (background, color, tint), so a worker can drive per-item theming, not just text. They CANNOT target strict-enum fields (style, size, alignment, severity, presentation, …) — those fail at render, not validation.",
+    "A screen that loads data asynchronously ships a designed LOADING state with it — a `Skeleton` shaped like the loaded layout when that layout is known (`StatefulSection` or `ActivityIndicator` when they fit the behavior better) — and a REDESIGN of a data screen reviews and updates that loading state in the same change, so it never shows the old layout. Loading is its own state, never the empty or the error state; a static screen gets no loading state (`himi docs designing-himi-screens` §5).",
     "Workers are sandboxed: no DOM, no timers, no raw fetch. Produce state synchronously in actions; do not rely on an ambient refresh tick.",
     "Declare every capability a worker uses in TWO places: the calling screen's logicBundle.declaredCapabilities (wix_platform, stream, camera, location, …) — undeclared calls are blocked — AND config.ts `capabilities`, the app-level list a binary is built with. The `capabilities` guide shows each id's import, what the binary needs and which shells serve it; validate flags an unknown id, an undeclared call, and (with `shell` in himalaya.content.json) an id that shell's binary does not serve. A capability with a native footprint (camera, location, push, …) only arrives with a new binary — an over-the-air push cannot add it. EXCEPTION: the Wix REST bridge (wix_api — the @himalaya/wix-* clients / wixApi.call) is ungated today (installed unconditionally), so it works WITHOUT a declaration; declaring wix_api is still recommended — it is where the platform is heading, and it documents what your worker touches.",
     "`validate`/`render` prove a screen is WELL-FORMED and, by default, paint its INITIAL state — NOT that the app's LOGIC is correct. A wrong reducer (a game that never ends, a bad total) passes both with ok:true. Run `himi test`: it needs NO test files — it boots each screen's real worker and dispatches every action your descriptor already declares, then reports anything that threw, stayed stuck on `loading`, or leaked a NaN/undefined/`$service:` token into visible text. It crawls on HERMETIC DATA by default (zero network): your `dev/net-mocks.json` first, then your config's CMS `seed:` rows, then a canned fixture of frozen real vertical responses shipped with the CLI — so the fetch-SUCCESS mapping path runs too, where data-shape bugs actually live (canned data exercises code paths, not API-contract truth). Two boot-only HOSTILE passes (every list empty; every request 500) then check the empty/outage day — their findings are errors, not warnings. It also runs the worker in a DEVICE-PARITY sandbox (no setTimeout/setInterval, as on JSC/WebView), so a bundle that would only die on the device fails locally instead — e.g. `svc.actions.load(…)` (actions are DIRECT methods; `.actions` is undefined on device). (You are NOT limited to the crawled states either: rendering with `--live` runs the worker's REAL fetches against live Wix — a minted anonymous visitor token from the app's clientId — so a render CAN prove real-data binding locally with no VPN/push; and injecting `state` (`{\"<svc>\":{…}}`) renders a specific mid-flow state without the network.)",