@wix/himalaya-cli 0.1156.0 → 0.1158.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/dev-server/src/builder.d.ts

@@ -137,6 +137,8 @@ export interface WebViewConfig {
     coverBandColor?: string;
     hideWixAds?: boolean;
     hideHostedSiteFooter?: boolean;
+    sessionBridge?: boolean;
+    hostedSiteAdapter?: "" | "wix" | "base44";
 }
 export declare function vstack(props: {
     spacing?: number;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/schema.d.ts

@@ -3036,6 +3036,14 @@ export interface WebViewConfig {
      * script, like {@link hideHostedSiteHeader}. No-op on web (cross-origin iframe).
      */
     hideHostedSiteFooter?: boolean;
+    /**
+     * RFC 0062 §5.8 — sign the page in natively. Runs only when {@link hostedSiteAdapter} names an
+     * adapter AND the app declares that adapter's capability; the host seeds the adapter's session
+     * into the page's own storage at document start, on the exact {@link allowedOrigins} only.
+     */
+    sessionBridge?: boolean;
+    /** RFC 0062 §5.8 — which site adapter the host runs: `""` (none) | `"wix"` | `"base44"`. */
+    hostedSiteAdapter?: "" | "wix" | "base44";
 }
 /**
  * Embeddable WebView component (web-in-SDUI). WebViews have no intrinsic height,

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/core/ts/src/validator.d.ts

@@ -1051,6 +1051,13 @@ export declare const screenDescriptorSchema: {
                 readonly hideHostedSiteFooter: {
                     readonly type: "boolean";
                 };
+                readonly sessionBridge: {
+                    readonly type: "boolean";
+                };
+                readonly hostedSiteAdapter: {
+                    readonly type: "string";
+                    readonly enum: readonly ["", "wix", "base44"];
+                };
             };
         };
     };
@@ -2012,6 +2019,13 @@ export declare const widgetSnapshotSchema: {
                 readonly hideHostedSiteFooter: {
                     readonly type: "boolean";
                 };
+                readonly sessionBridge: {
+                    readonly type: "boolean";
+                };
+                readonly hostedSiteAdapter: {
+                    readonly type: "string";
+                    readonly enum: readonly ["", "wix", "base44"];
+                };
             };
         };
     };

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

@@ -8634,7 +8634,10 @@ var screenDescriptorSchema = {
         coverBandColor: { type: "string" },
         // RFC 0062 — binary-shipped chrome hiding for a hosted site (no page script over the air).
         hideWixAds: { type: "boolean" },
-        hideHostedSiteFooter: { type: "boolean" }
+        hideHostedSiteFooter: { type: "boolean" },
+        // RFC 0062 §5.8 — the native session bridge (fields 47/48).
+        sessionBridge: { type: "boolean" },
+        hostedSiteAdapter: { type: "string", enum: ["", "wix", "base44"] }
       }
     }
   }
@@ -13169,6 +13172,10 @@ function siteWebViewPreset(site) {
     hideHostedSiteFooter: chrome.hideSiteFooter,
     // Wix ads only exist on Wix free sites; a Base44 site never gets the Wix selectors.
     hideWixAds: site.kind === "wix" && chrome.hideWixAds,
+    // RFC 0062 §5.8 — a Base44 app is signed in natively and its session carried into the page.
+    // The host still refuses unless the app declares the `base44` capability. Wix keeps its
+    // item-2 bridge (not built yet), so a Wix site carries neither field.
+    ...site.kind === "base44" ? { hostedSiteAdapter: "base44", sessionBridge: true } : {},
     pullToRefresh: true,
     showProgressBar: true,
     syncStatusBarAppearance: true,

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

@@ -7587,7 +7587,10 @@ var screenDescriptorSchema = {
         coverBandColor: { type: "string" },
         // RFC 0062 — binary-shipped chrome hiding for a hosted site (no page script over the air).
         hideWixAds: { type: "boolean" },
-        hideHostedSiteFooter: { type: "boolean" }
+        hideHostedSiteFooter: { type: "boolean" },
+        // RFC 0062 §5.8 — the native session bridge (fields 47/48).
+        sessionBridge: { type: "boolean" },
+        hostedSiteAdapter: { type: "string", enum: ["", "wix", "base44"] }
       }
     }
   }

package/dist/cli.mjs

@@ -6834,6 +6834,7 @@ function resolveTranslation(value, catalog, sourceCatalog) {
 var BINDING_SIGILS, BINDING_SIGIL_RE, TRANSLATION_PREFIX, TRANSLATION_KEY_RE;
 var init_bindings = __esm({
   "../../core/ts/src/bindings.ts"() {
+    "use strict";
     BINDING_SIGILS = ["service", "flag", "item", "t"];
     BINDING_SIGIL_RE = new RegExp(
       `^\\$(?:${BINDING_SIGILS.filter((s) => s !== "t").join("|")})\\b|^\\$t:`
@@ -7672,7 +7673,10 @@ var init_validator = __esm({
             coverBandColor: { type: "string" },
             // RFC 0062 — binary-shipped chrome hiding for a hosted site (no page script over the air).
             hideWixAds: { type: "boolean" },
-            hideHostedSiteFooter: { type: "boolean" }
+            hideHostedSiteFooter: { type: "boolean" },
+            // RFC 0062 §5.8 — the native session bridge (fields 47/48).
+            sessionBridge: { type: "boolean" },
+            hostedSiteAdapter: { type: "string", enum: ["", "wix", "base44"] }
           }
         }
       }
@@ -73422,6 +73426,7 @@ function pageId(c, used) {
 }
 function deriveSiteShell(input) {
   const origin = normalizeSiteOrigin(input.siteUrl);
+  const kind = input.kind ?? siteKindForOrigin(origin);
   const notes = [];
   const published = input.look.sitePages ?? [];
   const mainPageId = input.look.mainPageId;
@@ -73440,7 +73445,14 @@ function deriveSiteShell(input) {
   };
   const navLinks = input.look.navLinks ?? [];
   let homeTitle = "Home";
-  if (navLinks.length) {
+  const routes = (input.routes ?? []).filter((r) => isNavigableRoute(r.path));
+  if (routes.length) {
+    for (const r of routes) {
+      const path2 = r.path.startsWith("/") ? r.path : `/${r.path}`;
+      add(routeTitle(r), path2, `${origin.replace(/\/$/, "")}${path2}`);
+    }
+    notes.push(`site pages: taken from the Base44 app book's ${routes.length} route(s) \u2014 edit \`site.pages\` to rename or reorder them.`);
+  } else if (navLinks.length) {
     for (const link of navLinks) {
       const path2 = pathOnSite(origin, link.href);
       if (path2 === null) continue;
@@ -73501,22 +73513,39 @@ function deriveSiteShell(input) {
       ...placement === "tab" ? {} : { placement }
     }))
   ];
-  if (!published.length && !navLinks.length) {
+  if (!published.length && !navLinks.length && !routes.length) {
     notes.push("site pages: the analysis read no page list, so the map has only Home \u2014 add the site's pages to `site.pages` before --apply.");
   }
   const site = {
     origin,
-    kind: "wix",
+    kind,
     pages,
     // Hidden by default — the product decision for the site shell (RFC 0062 §6); the owner can
-    // turn any of them back on here, and the flags ride the OTA descriptor.
-    chrome: { hideSiteHeader: true, hideSiteFooter: true, hideWixAds: true }
+    // turn any of them back on here, and the flags ride the OTA descriptor. A Base44 app has no
+    // Wix ads to hide, so it never carries the flag (RFC 0062 §5.8).
+    chrome: kind === "wix" ? { hideSiteHeader: true, hideSiteFooter: true, hideWixAds: true } : { hideSiteHeader: true, hideSiteFooter: true }
   };
   assertSiteShellConfig(site);
   const tabTitles = pages.filter((p) => (p.placement ?? "tab") === "tab").map((p) => p.title);
   notes.unshift(`site pages: ${pages.length} derived \u2014 tabs ${tabTitles.join(", ")}; edit \`site.pages\` in provisioning.overlay.json to change them.`);
   return { site, notes };
 }
+function siteKindForOrigin(origin) {
+  const host = new URL(origin).hostname.toLowerCase();
+  const isBase44 = ["base44.app", "base44.com"].some((d) => host === d || host.endsWith(`.${d}`));
+  return isBase44 ? "base44" : "wix";
+}
+function isNavigableRoute(path2) {
+  const p = path2.trim();
+  if (!p || p === "/" || p.includes(":") || p.includes("*")) return false;
+  return !/^\/?(login|signin|sign-in|register|signup|logout)(\/|$)/i.test(p);
+}
+function routeTitle(r) {
+  const fromComponent = r.component?.replace(/(Page|Screen|View)$/, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").trim();
+  if (fromComponent) return fromComponent;
+  const seg = r.path.split("/").filter(Boolean).pop() ?? r.path;
+  return seg.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
 var DERIVED_SITE_MAX_PAGES, SITE_PAGE_TITLE_MAX, ROLE_ICON, TAB_ROLES, SYSTEM_SEGMENT, SYSTEM_TITLE, HOME_WORD, oneLine2;
 var init_site_shell_derive = __esm({
   "src/site-analyze/site-shell-derive.ts"() {
@@ -74174,12 +74203,13 @@ __export(cli_exports2, {
   SITE_FUNCTION_USAGE: () => SITE_FUNCTION_USAGE,
   applyNeedsClient: () => applyNeedsClient,
   assetFetchFor: () => assetFetchFor,
+  base44BookRoutes: () => base44BookRoutes,
   noteWithWarnings: () => noteWithWarnings,
   ownerSiteFor: () => ownerSiteFor,
   runSiteAnalyze: () => runSiteAnalyze,
   runSiteFunctionCli: () => runSiteFunctionCli
 });
-import { readFileSync as readFileSync88 } from "node:fs";
+import { existsSync as existsSync71, readFileSync as readFileSync88 } from "node:fs";
 import { resolve as resolve55 } from "node:path";
 function applyNeedsClient(shell) {
   if (shell === void 0 || !SHELL_NAMES2.includes(shell)) return true;
@@ -74230,7 +74260,11 @@ async function runSiteAnalyze(opts) {
   );
   if (opts.shell !== void 0 && isSiteShell(opts.shell)) {
     try {
-      const derived = deriveSiteShell({ siteUrl: result.book.input.siteUrl, look: result.book.look });
+      const kind = siteKindForOrigin(result.book.input.siteUrl);
+      const book = kind === "base44" ? base44BookRoutes(resolve55(cwd, ".himi/base44-book/book.json"), result.book.input.siteUrl) : void 0;
+      const routes = book?.routes;
+      if (book?.skipped) result.warnings = [...result.warnings ?? [], book.skipped];
+      const derived = deriveSiteShell({ siteUrl: result.book.input.siteUrl, look: result.book.look, kind, routes });
       result.provisioningOverlay.site = derived.site;
       const warnings2 = (result.warnings ?? []).map(
         (w) => !opts.clientId?.trim() && w.startsWith("no --client-id:") ? `no --client-id: fine for --shell ${opts.shell} \u2014 a site shell binds no client, so --apply works without one. Only the vertical probes were skipped, so the catalog has no counts.` : w
@@ -74325,6 +74359,30 @@ async function runSiteFunctionCli(opts) {
     fetchImpl: opts.fetchImpl
   });
 }
+function base44BookRoutes(bookPath, siteUrl) {
+  if (!existsSync71(bookPath)) return void 0;
+  try {
+    const book = JSON.parse(readFileSync88(bookPath, "utf8"));
+    if (book.kind !== "base44-app-book" || !Array.isArray(book.routes)) return void 0;
+    const host = (u) => {
+      try {
+        return typeof u === "string" ? new URL(u).host.toLowerCase() : "";
+      } catch {
+        return "";
+      }
+    };
+    const want = host(siteUrl);
+    const have = [host(book.input?.url), host(book.identity?.publishedUrl)].filter(Boolean);
+    if (!have.includes(want)) {
+      return { skipped: `site pages: ignored .himi/base44-book \u2014 it was read from ${have[0] || "an unknown app"}, not ${want}; re-run \`himi base44 analyze --url ${siteUrl}\` for this site.` };
+    }
+    return {
+      routes: book.routes.filter((r) => !!r && typeof r.path === "string").map((r) => ({ path: r.path, ...typeof r.component === "string" ? { component: r.component } : {} }))
+    };
+  } catch {
+    return void 0;
+  }
+}
 var APPLY_NEEDS_CLIENT, FUNCTION_OPS;
 var init_cli2 = __esm({
   "src/site-analyze/cli.ts"() {
@@ -74559,7 +74617,7 @@ __export(site_create_exports, {
   runSiteList: () => runSiteList,
   writeProvisioningBinding: () => writeProvisioningBinding
 });
-import { existsSync as existsSync71, readFileSync as readFileSync89, writeFileSync as writeFileSync34 } from "node:fs";
+import { existsSync as existsSync72, readFileSync as readFileSync89, writeFileSync as writeFileSync34 } from "node:fs";
 import { resolve as resolvePath2 } from "node:path";
 function oauthClientName(projectName) {
   return `${projectName} client`;
@@ -74708,7 +74766,7 @@ async function runSiteCreate(opts) {
   if (!wantOauthApp) return { ...base, nextSteps: nextSteps(metaSiteId) };
   return { ...base, clientId, redirectUri, nextSteps: nextSteps(metaSiteId, clientId) };
 }
-function writeProvisioningBinding(target, binding2, fs = { existsSync: existsSync71, readFileSync: readFileSync89, writeFileSync: writeFileSync34 }) {
+function writeProvisioningBinding(target, binding2, fs = { existsSync: existsSync72, readFileSync: readFileSync89, writeFileSync: writeFileSync34 }) {
   const msid = binding2.siteId;
   const path2 = resolvePath2(target);
   const committed = committedShellProvisioning(path2);
@@ -75381,7 +75439,7 @@ var init_context = __esm({
 });
 
 // src/cli.ts
-import { mkdtempSync as mkdtempSync5, readFileSync as readFileSync90, mkdirSync as mkdirSync39, writeFileSync as writeFileSync35, existsSync as existsSync72, rmSync as rmSync20, readdirSync as readdirSync32, statSync as statSync20, lstatSync as lstatSync17, accessSync, constants as constants3, renameSync as renameSync9, cpSync as cpSync3 } from "node:fs";
+import { mkdtempSync as mkdtempSync5, readFileSync as readFileSync90, mkdirSync as mkdirSync39, writeFileSync as writeFileSync35, existsSync as existsSync73, rmSync as rmSync20, readdirSync as readdirSync32, statSync as statSync20, lstatSync as lstatSync17, accessSync, constants as constants3, renameSync as renameSync9, cpSync as cpSync3 } from "node:fs";
 import { execFile as execFile2, execFileSync as execFileSync7, spawnSync as spawnSync5, spawn as spawn7 } from "node:child_process";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash as createHash36, randomUUID as randomUUID8 } from "node:crypto";
@@ -78609,7 +78667,7 @@ function createUpdateRunner(spawn8 = spawnSync5) {
     reexec: (argv) => {
       const root = globalNodeModulesRoot();
       const entry = root ? join74(root, "@wix", "himalaya-cli", "dist", "cli.mjs") : void 0;
-      if (!entry || !existsSync72(entry)) return void 0;
+      if (!entry || !existsSync73(entry)) return void 0;
       const result = spawnSync5(process.execPath, [entry, ...argv], {
         // inherit keeps PIPED STDIN working — commands that read stdin must survive a re-exec.
         stdio: "inherit",
@@ -79380,7 +79438,7 @@ async function nativeConfigAdvisories(app, configSource) {
     const { iosProjectYml: iosProjectYml2 } = await Promise.resolve().then(() => (init_paths2(), paths_exports));
     const { androidOptedIn: androidOptedIn3, LABEL_IOS_SPLASH: LABEL_IOS_SPLASH2 } = await Promise.resolve().then(() => (init_splash(), splash_exports));
     const iosYmlPath = iosProjectYml2(app);
-    const iosYml = existsSync72(iosYmlPath) ? readFileSync90(iosYmlPath, "utf8") : "";
+    const iosYml = existsSync73(iosYmlPath) ? readFileSync90(iosYmlPath, "utf8") : "";
     let optedIn = iosYml.includes(LABEL_IOS_SPLASH2);
     if (!optedIn) {
       const { androidManifestPath: androidManifestPath3 } = await Promise.resolve().then(() => (init_gen_native_config(), gen_native_config_exports));
@@ -79446,7 +79504,7 @@ function keptPlan(kept) {
 }
 async function initFromRemoteTemplate(name, parentDir, template, c) {
   const dir = resolve56(parentDir, name);
-  if (existsSync72(join74(dir, "himalaya.content.json"))) {
+  if (existsSync73(join74(dir, "himalaya.content.json"))) {
     throw new Error(`content package already exists at ${dir}`);
   }
   const r = await c.fetchTemplateSource(TEMPLATE_APP_PREFIX + template);
@@ -79489,7 +79547,7 @@ function symlinkDestinationIssue(dest) {
 function restoreDestinationIssue(dest, force) {
   const link = symlinkDestinationIssue(dest);
   if (link) return link;
-  if (!existsSync72(dest)) return null;
+  if (!existsSync73(dest)) return null;
   if (!statSync20(dest).isDirectory()) {
     return { error: `${dest} exists and is not a directory`, hint: "pass --out/--name to land somewhere else, or remove the file" };
   }
@@ -79504,7 +79562,7 @@ function restoreDestinationIssue(dest, force) {
 function isHimalayaMonorepoCheckout(start) {
   let dir = resolve56(start);
   for (; ; ) {
-    if (existsSync72(join74(dir, "tools", "himi-cli", "src", "cli.ts")) && existsSync72(join74(dir, "core", "serve", "src", "server.ts"))) return true;
+    if (existsSync73(join74(dir, "tools", "himi-cli", "src", "cli.ts")) && existsSync73(join74(dir, "core", "serve", "src", "server.ts"))) return true;
     const parent = dirname40(dir);
     if (parent === dir) return false;
     dir = parent;
@@ -79832,7 +79890,7 @@ Seed your coding agent with \`himi agent-init\`. Guides: ${idx.portalUrl}`);
         ...res.removed.length ? { removed: res.removed, note: "older copies at the app root, moved to .himi/legacy-agent-files/ (a backup, in case one became app code) \u2014 the current ones live in .agents/skills/himalaya/" } : {},
         // In a git repo the refresh moves the diff identity an earlier `himi test` attested (that
         // hash is shared with the repo gates and deliberately exempts nothing but its own metadata).
-        ...existsSync72(join74(dir, ".himi", "attestations", "latest.json")) ? { next: "if `himi push` then refuses the attestation as stale, re-run `himi test` \u2014 in a git checkout this refresh changed the tree it covered" } : {},
+        ...existsSync73(join74(dir, ".himi", "attestations", "latest.json")) ? { next: "if `himi push` then refuses the attestation as stale, re-run `himi test` \u2014 in a git checkout this refresh changed the tree it covered" } : {},
         ...res.skipped.length ? { skipped: res.skipped } : {},
         portalUrl: idx.portalUrl
       });
@@ -80065,7 +80123,7 @@ async function producedWidgetFamilies(dir) {
   }
   return { families, source: "dist/bundles" };
 }
-var boardOpen = (dir) => existsSync72(join74(dir, ".himi", "studio", "index.html"));
+var boardOpen = (dir) => existsSync73(join74(dir, ".himi", "studio", "index.html"));
 var BOARD_REFRESHERS = /* @__PURE__ */ new Set(["render", "test", "validate", "build", "push", "icon", "site", "ux", "progress"]);
 async function leaveForBoard(dir, record2, value) {
   if (!boardOpen(dir)) return;
@@ -80381,7 +80439,7 @@ himi v${cliVersion()} \u2014 run \`himi --version\`. If authoring commands fail
             const owed = openApprovals2(readApprovals2(dir).events).length;
             next.push(`carried the planning journal into the app (${carried.join(", ")}${owed ? `; ${owed} approval${owed === 1 ? "" : "s"} still owed` : ""}) \u2014 \`himi progress --brief\` there shows it`);
           }
-          const planInParent = ["SPEC.md", "MOBILE-UX.md"].filter((f) => existsSync72(join74(parentDir, f)));
+          const planInParent = ["SPEC.md", "MOBILE-UX.md"].filter((f) => existsSync73(join74(parentDir, f)));
           if (planInParent.length) {
             next.push(`${planInParent.join(" and ")} in ${parentDir} ${planInParent.length > 1 ? "are" : "is"} not the app's \u2014 if that is the approved plan, move it over the template's boilerplate in ${dir}`);
           }
@@ -80661,7 +80719,7 @@ ${doNow.map((l) => `  ${l}`).join("\n")}`);
           const result = { ...outcome.result, ...fromSpec };
           const adoptDir = contentDir(flags);
           const kept = flags["dry-run"] !== true && (outcome.code === 0 || outcome.result.forcedKeep === true);
-          if (kept && existsSync72(join74(adoptDir, adoptBits.ADOPT_FILE))) {
+          if (kept && existsSync73(join74(adoptDir, adoptBits.ADOPT_FILE))) {
             try {
               const inv = adoptBits.inspectApp(adoptDir);
               adoptBits.writeInventory(adoptDir, inv, { companions: "if-missing" });
@@ -81225,7 +81283,7 @@ ${doNow.map((l) => `  ${l}`).join("\n")}`);
       case "studio": {
         const { openStudio: openStudio2 } = await Promise.resolve().then(() => (init_studio(), studio_exports));
         const dir = contentDir(flags);
-        if (!existsSync72(join74(dir, "himalaya.content.json"))) {
+        if (!existsSync73(join74(dir, "himalaya.content.json"))) {
           io.error(JSON.stringify({ ok: false, error: "not_a_content_package", dir, hint: "run from the app directory (or pass --content <dir>) \u2014 the board reads that package's .himi/" }));
           return 2;
         }
@@ -81303,7 +81361,7 @@ ${handover.hint[0].toUpperCase()}${handover.hint.slice(1)}.`);
         } = await Promise.resolve().then(() => (init_progress(), progress_exports));
         const dir = contentDir(flags);
         const journal2 = journalPath2(dir);
-        const isContentPackage = existsSync72(join74(dir, "himalaya.content.json"));
+        const isContentPackage = existsSync73(join74(dir, "himalaya.content.json"));
         const hint = isContentPackage ? {} : { hint: "no himalaya.content.json here \u2014 run from the app directory (or pass --content <dir>) so the build board finds this journal" };
         const message = pos.slice(1).join(" ").trim();
         const approvalFlags = ["approve", "done", "drop"].filter((f) => flags[f] !== void 0);
@@ -81455,7 +81513,7 @@ ${handover.hint[0].toUpperCase()}${handover.hint.slice(1)}.`);
       case "test": {
         const dir = contentDir(flags);
         const structuredOutput = flags.json === true || io.isTTY !== true;
-        if (existsSync72(join74(dir, "functions"))) {
+        if (existsSync73(join74(dir, "functions"))) {
           const { invokeLocalFunction: invokeLocalFunction2, loadFunctionsApp: loadFunctionsApp2 } = await Promise.resolve().then(() => (init_functions(), functions_exports));
           const loaded = await loadFunctionsApp2(dir);
           const results = [];
@@ -82386,7 +82444,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           io.error(JSON.stringify(linked));
           return 1;
         }
-        if (existsSync72(dest)) {
+        if (existsSync73(dest)) {
           if (!statSync20(dest).isDirectory()) {
             io.error(JSON.stringify({
               error: `${dest} exists and is not a directory`,
@@ -82399,7 +82457,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
             io.error(JSON.stringify({ error: `${dest} already exists and is not empty`, hint: "pass --force to write into it anyway (merging, and naming what it keeps), --replace to restore exactly what was archived, or --out/--name to land somewhere else" }));
             return 1;
           }
-          if (replace && occupied && !existsSync72(join74(dest, "himalaya.content.json"))) {
+          if (replace && occupied && !existsSync73(join74(dest, "himalaya.content.json"))) {
             io.error(JSON.stringify({
               error: `${dest} is not a content package \u2014 refusing to --replace it`,
               hint: "--replace only clears a directory that holds himalaya.content.json. Check --out/--name, or pass --force to merge into it instead."
@@ -84162,7 +84220,7 @@ default (no --glyph): ${DEFAULT_GLYPH2} \u2014 a mark that claims nothing, so th
           io.error(JSON.stringify({ error: `patch ${kind} needs --file`, usage: PATCH_USAGE }));
           return 2;
         }
-        if (!existsSync72(file)) {
+        if (!existsSync73(file)) {
           io.error(JSON.stringify({ error: `no such file: ${file}` }));
           return 2;
         }
@@ -84885,7 +84943,7 @@ ${label2}`);
         const platform = str9(flags.platform)?.split(",").map((p) => p.trim()).filter(Boolean);
         {
           const distDir = contentDir(flags);
-          if (existsSync72(join74(distDir, "himalaya.content.json"))) {
+          if (existsSync73(join74(distDir, "himalaya.content.json"))) {
             const issues = await iconIssues(distDir, flags.strict === true, { requireDeclared: true, requireVerified: true });
             const errors = issues.filter((i) => i.severity === "error");
             for (const i of issues.filter((i2) => i2.severity === "warning")) {

package/guides/himi-skill.md

@@ -450,6 +450,14 @@ I want to create a mobile app for my business. Follow this skill:
 https://apps.wix.com/_api/himi-serve/skill.md
 ```
 
+## Home-screen widgets
+
+Read `himi docs widgets` **before** you write a `defineWidget`. A widget is a frozen poster frame:
+its `render` runs once, at build time, over each service's **initial** `state`. Actions, `fetch` and
+Wix data never reach it, and there is no live-data path yet, so a widget written over fetched data
+ships its placeholder. Design it around initial state, constants or a `timeline`, and deep-link the
+tap into the screen that has the live data.
+
 ## Native UX evidence gate
 
 Before declaring a multi-screen app ready, run `himi ux audit --content . --strict` and resolve its findings. After driving each available native shell, persist the actual checks with `himi ux record`; record an unavailable platform with its reason rather than claiming coverage.

package/guides/index.json

@@ -190,6 +190,12 @@
       "category": "Workers & SDKs",
       "file": "cms-collections.md"
     },
+    {
+      "id": "widgets",
+      "title": "Home-screen widgets (what a widget can show)",
+      "category": "Workers & SDKs",
+      "file": "widgets.md"
+    },
     {
       "id": "wix-sdk-overview",
       "title": "Wix SDK overview (front door)",

package/guides/widgets.md

@@ -0,0 +1,233 @@
+# Home-screen widgets
+
+A widget is a **frozen poster frame** of your app. It is drawn by the operating system on a home
+screen, lock screen or watch face, and opened with a tap. Your worker never runs
+inside it. This page explains where a widget's content comes from, because that is the part that
+surprises people: **a widget shows what your worker's state is at build time, not what the worker
+later fetches.**
+
+## The one rule: a widget renders initial state, once
+
+You declare a widget with `defineWidget` in the same worker file as your `defineService`:
+
+```ts
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineWidget("<widget id>", {
+  family: "ios_home",   // which OS surface — see the table below
+  size: "small",
+  deepLink: "<your app scheme>://screen/<screen id>",
+  refresh: { ttlSeconds: 900 },
+  render: (services) => ({ /* a component tree of literals */ }),
+});
+```
+
+When your app is built or served, the platform **produces** each widget:
+
+1. It evaluates your worker in a sandbox and records each `defineService`'s **initial `state`**.
+2. It calls `render(services)` **once, synchronously**, where `services` is
+   `{ <service name>: <its initial state> }`.
+3. It freezes the tree `render` returned and serves it as the widget's snapshot.
+
+So, inside that sandbox:
+
+| What your worker does | What the widget sees |
+|---|---|
+| `state: { … }` in `defineService` | ✅ exactly that object |
+| Constants and plain functions in the file | ✅ available to `render` |
+| An action (`load`, `refresh`, …), sync or `async` | ❌ never runs — the widget keeps the initial state |
+| `fetch`, Wix data queries, any Wix SDK call | ❌ `fetch` throws; nothing it would return arrives |
+| `setTimeout` / `setInterval` | ❌ never fire |
+| `$service:` / `$item` bindings in the tree | ❌ rejected — the snapshot must be literals |
+
+`render` must therefore be **synchronous and side-effect free**: no network, no awaiting, no
+bindings, only **resolved literal values**. Reading the clock is the one allowed dependency.
+`Date.now()` works and is evaluated at produce time, so a value computed from it is as fresh as
+the last produce (see [refresh](#refresh-taps-and-previews)). A `render` that throws, or returns a
+tree with a binding in it, makes that widget fail to produce.
+
+### There is no live-data path yet
+
+Data your worker fetches **cannot** reach a widget today. `refresh.pushTopic` exists in the type
+definitions, but nothing consumes it yet: setting it does not make the widget update when data
+changes. Plan the widget around what you know when the app is built — a call to action, a
+constant, or a schedule (see [timelines](#content-whose-future-you-know-live-time-and-timelines)) — and let the
+tap take the user into the app, where the live data is.
+
+## A widget that stays inside the contract
+
+This widget shows the studio's name and a fixed call to action, both from initial state. Tapping
+it opens the booking screen, which loads the real schedule.
+
+<!-- widget-example: within-contract -->
+```ts
+import { defineService } from "@wix/himalaya/state";
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineService("studio", {
+  state: { name: "Harbor Yoga", cta: "Book your next class" },
+});
+
+defineWidget("studio.book", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "harboryoga://screen/book",
+  refresh: { ttlSeconds: 86400 },
+  render: (services) => {
+    const studio = services.studio as { name: string; cta: string };
+    return {
+      id: "root",
+      body: { package: "himalaya", type: "VStack", props: { spacing: 4, children: [
+        { id: "name", body: { package: "himalaya", type: "Text", props: { text: studio.name, style: "headline" } } },
+        { id: "cta", body: { package: "himalaya", type: "Text", props: { text: studio.cta, style: "caption" } } },
+      ] } },
+    };
+  },
+});
+```
+
+It produces exactly this frozen tree:
+
+<!-- widget-example: within-contract.payload -->
+```json
+{
+  "id": "root",
+  "body": { "package": "himalaya", "type": "VStack", "props": { "spacing": 4, "children": [
+    { "id": "name", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Harbor Yoga", "style": "headline" } } },
+    { "id": "cta", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Book your next class", "style": "caption" } } }
+  ] } }
+}
+```
+
+## The mistake: a widget over fetched data
+
+This is the natural way to write it, and it ships the placeholder:
+
+<!-- widget-example: anti-pattern -->
+```ts
+import { defineService } from "@wix/himalaya/state";
+import { defineWidget } from "@wix/himalaya/widget";
+
+defineService("latest", {
+  state: { title: "Loading…" },
+  actions: {
+    async load(s) {
+      const res = await fetch("https://example.com/latest.json");
+      const { title } = (await res.json()) as { title: string };
+      return { ...s, title };
+    },
+  },
+});
+
+defineWidget("latest.story", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "myapp://screen/home",
+  refresh: { ttlSeconds: 900 },
+  render: (services) => ({
+    id: "w",
+    body: { package: "himalaya", type: "Text", props: { text: (services.latest as { title: string }).title } },
+  }),
+});
+```
+
+`load` never runs at produce time, so `render` reads the initial state and the widget says
+"Loading…" forever:
+
+<!-- widget-example: anti-pattern.payload -->
+```json
+{ "id": "w", "body": { "package": "himalaya", "type": "Text", "props": { "text": "Loading…" } } }
+```
+
+Calling the action yourself at the top level (`svc.load()`) does not help either: at produce time
+every action resolves to the initial state.
+
+## Content whose future you know: live time and timelines
+
+**Countdowns and clock text: `Text.timeRef`.** A `Text` with
+`timeRef: { at: <epoch seconds>, style: "timer" | "relative" | "date" | "time" | "offset" }`
+shows a time value that overrides the `Text`'s `text`. How live it is depends on the platform:
+
+- **iPhone (home, lock, Live Activity)**: the OS ticks it every second, with no refresh and no worker.
+- **Android home screen**: it is formatted only when the widget is redrawn, which the OS
+  schedules (typically no more often than every 15 minutes), so do not rely on it to count seconds.
+- **`web_card`**: `timeRef` is ignored and the `Text`'s own `text` is shown, so always set a
+  `text` fallback.
+
+```ts
+{ id: "starts", body: { package: "himalaya", type: "Text",
+  props: { text: "Starts soon", timeRef: { at: Math.floor(Date.now() / 1000) + 3600, style: "timer" } } } }
+```
+
+**Discrete future states: `timeline`.** When you know in advance which *different content* the
+widget should show later — today's agenda, a streak that resets at midnight — add a `timeline`. It returns frozen frames, each with the epoch
+second it becomes current, and the OS advances through them with no network and no worker:
+
+```ts
+// frame(title, time) returns a component tree; DAY_START is today's midnight in epoch seconds.
+defineWidget("studio.agenda", {
+  family: "ios_home",
+  size: "small",
+  deepLink: "harboryoga://screen/schedule",
+  refresh: { ttlSeconds: 900 },
+  render: () => frame("Morning flow", "7:00"),            // also frame 0 for older clients
+  timeline: () => [
+    { startsAt: DAY_START + 7 * 3600, component: frame("Morning flow", "7:00") },
+    { startsAt: DAY_START + 12 * 3600, component: frame("Lunch stretch", "12:00") },
+  ],
+});
+```
+
+`timeline` follows the same rule as `render`: synchronous, no network, literals only. It is
+evaluated at produce time, so its frames are only as current as the last produce, and it keeps at
+most 48 frames — never bake a second-by-second countdown into it; that is what `timeRef` is for.
+
+## Families and sizes
+
+| `family` | Surface |
+|---|---|
+| `ios_home` | iPhone home screen |
+| `ios_lock` | iPhone lock screen |
+| `android_home` | Android home screen |
+| `web_card` | A card on the web preview |
+| `ios_live_activity` | iPhone Live Activity |
+| `watch_complication` | Watch face complication |
+
+`size` is the OS size hint: `small`, `medium` or `large` for home-screen widgets, and `inline`,
+`circular` or `rectangular` for lock-screen and complication slots.
+
+One worker can declare several widgets, one per family and size. To give a widget a *different
+layout* from your phone screen while reading the same services, use `defineView` with a
+`widget:<family>` surface instead. It is the same frozen contract, chosen per surface, and
+`size`, `deepLink`, `refresh` and `timeline` are accepted only on those frozen surfaces.
+
+**In-car screens are not a widget family.** The car display is authored with
+`defineView("<view id>", { surface: "car", deepLink, refresh, render })`: frozen like a widget,
+with the same rules for `render`. `deepLink` and `refresh` are required, as for a widget; `size` is
+not, because the car lays out its own rows. It never goes through `defineWidget`.
+
+## Refresh, taps and previews
+
+- **`refresh.ttlSeconds`** is how long a snapshot may be served before it is produced again. A new
+  produce still renders the *initial* state, so a shorter TTL only helps content that is computed
+  from the clock at produce time. It does not make fetched data appear.
+- **`refresh.preferredRefreshSeconds`** (optional) is a hint to the OS background-refresh
+  scheduler about how often to redraw the widget; when unset, `ttlSeconds` is used. The OS may
+  clamp or defer it (Android never redraws more often than every 15 minutes), so treat it as a
+  request, not a schedule.
+- **`deepLink`** is where a tap takes the user. Point it at the screen that shows the live version
+  of what the widget summarises.
+- **Preview a widget** while you work: `himi run --watch --content .` serves it at
+  `GET /v1/widget/<widget id>`, and `GET /v1/widgets` lists every widget the app produces.
+  `himi surfaces --measure-widgets` reports which families your package actually produces.
+
+## What `himi validate` checks
+
+A widget is **declared** when a worker calls `defineWidget` (or `defineView` with a `widget:`
+surface). If a declared widget fails to produce — `render` threw, returned a binding, or used a
+component its family does not allow — `himi validate` reports `widget-not-produced`. It is a
+warning by default and an **error under `--strict`**, so a package cannot ship a widget it
+declared but that renders nothing.
+
+A widget that produces the *placeholder* (the mistake above) is not an error: it renders, it just
+shows initial state. Check the snapshot at `GET /v1/widget/<widget id>` before you ship.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1156.0",
+  "version": "0.1158.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -67,5 +67,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "5d6bcf8d364821a37f27c35e0d3c50376b277479f44cc1e94d5c6729"
+  "falconPackageHash": "e2949fb643b50db7dff29f93ca7ee3235cd80cdac4a32d59ba2f89a1"
 }