@wix/himalaya-cli 0.1579.0 → 0.1581.0

package/guides/one-app-to-himi-app.md

@@ -116,6 +116,15 @@ user request. Preserve the collected files as evidence. Read the [versioned
 reference index](https://apps.wix.com/_api/himi-serve/docs/one-app-reference.md) and its five guides before interpreting
 settings or claiming coverage.
 
+When raw source placements reference `pages_section`, collection also saves
+`pages-content.json`. It selects `settings.value.pageId`, reads only those unique
+documents as the site's Visitor, and retains every original placement separately.
+The evidence records capture time, source identity, a serialized response JSON SHA-256,
+decoded content and an editable native RichContent component per placement.
+The hash identifies that captured response, not an invented server revision.
+Recollect to refresh editorial content; a changed response produces a changed hash.
+Never import the evidence directory into runtime code.
+
 An unavailable supporting runtime view is recorded as `runtime_context_unavailable`
 with its platform and typed failure code; that enriched file is absent. Continue
 from authored intent and mark the platform behavior as unverified in the report.
@@ -500,16 +509,69 @@ Apply these interpretation rules:
   alone does not prove native navigation or control availability. Record any
   unavailable device check as unverified.
 - Business context contains `phoneNumber`, `website`, `services`, optional public
-  `contact`, and an optional validated public `memberCount`, with their permitted
-  nested values. Structure wins on authored phone/URL/design.
+  `contact`, an optional validated public `memberCount`, and optional `displayName`
+  from the same-site Business title, with their permitted nested values.
+  Use `displayName` for business identity; structure wins on authored screen titles,
+  phone/URL/design.
   Installed services do not add features. Installation IDs are not record IDs.
-  Do not restore excluded Business titles, colors, identity or member fields.
+  Do not restore other excluded Business colors, identity or member fields.
 - Referenced editor-authored documents, such as Pages rich text, are presentation
   evidence too. Fetch only the referenced documents through verified read-only
   routes, record their IDs and versions, and reconstruct their authored content
   as editable native components. Keep changing business records live; do not
   substitute captured catalogs, memberships or transaction data for runtime reads.
 
+### Referenced Pages content
+
+`pages_section` is an editor-authored document selected by
+`settings.value.pageId`. It is not a CMS collection, Blog post or placeholder.
+Use `pages-content.json` to reconstruct each ready placement as editable app
+source, in its original layout array order, interleaved with the other sections.
+Repeated page IDs may share one captured document but retain separate placement
+IDs. Preserve source visibility/access rules and every screen alias that uses
+that layout; do not multiply canonical placements by navigation aliases.
+
+The collector's fixed read is
+`GET https://apps.wix.com/social-content/api/v1/pages/{pageId}` using the source
+site's Visitor signed instance. The response contains
+`{pageId, content: {title, body: {contentType, content}}}`. It verifies the returned
+page ID. `RICH_CONTENT` and `DRAFTJS` contain serialized JSON; `PLAIN_TEXT` stays
+literal. The pinned [original reader](https://github.com/wix-private/wix-one-app-pages/blob/5055bf29109c51c48f0009a403bb70976c54e8dc/packages/wix-one-app-pages/src/services/pages-api.ts "audience-lint-ok: optional pinned upstream evidence, not a local authoring dependency") documents this contract.
+No page listing, source mutation or manager credential fallback is needed.
+
+Use the emitted `placement.component`, or rebuild it with the screens SDK's
+`decodeOneAppPage(response, pageId)` and `oneAppPageSection(page, {id})`.
+Copy the resulting component into an editable app source file, then insert it
+into the actual generated screen's payload. Keep it outside collection-bound
+rows that a worker replaces on load. Rendering a separate unused sample or merely
+changing the catalog classification does not restore a migrated placement.
+The component uses literal `RichContent.documentJson`; no source prose is a
+service binding. The existing viewer preserves text, supported formatting, media
+and safe http(s)/mailto/tel links. Legacy bare website domains gain HTTPS before
+encoding; `normalizedWebsiteLinks` records the count. Relative paths, credentials
+and unsafe schemes do not gain an implicit origin. Root editor metadata is omitted from rendered
+content. Keep normal RichContent links or use the existing rich-link handler;
+do not replace them with generic navigation or a WebView.
+
+`ready` and genuine `empty` are successful captures. The section helper renders an
+empty page's message from optional `emptyTitle` / `emptyDescription`; localize
+that copy to the app and preserve the source empty-state intent. `invalid` (including missing
+or malformed selectors/content), `unsupported`, `forbidden`, `unauthorized`,
+`not_found` and `unavailable` remain distinct gaps. A failed document has no
+emitted component. Preserve the gap and resolve it before claiming its coverage;
+never substitute an empty paragraph, demo copy or owner read. Supported DraftJS
+text, styled links, flat lists, headings and images are converted; nested lists
+and unknown plugins remain explicit `unsupported` gaps.
+
+This reconstruction captures editorial presentation only. Changing catalogs,
+transactions and member records remain live. It uses the existing cross-platform
+RichContent component and does not require a new Pages endpoint in native/web
+runtime transports. A CLI/SDK source merge still needs its normal publication,
+and an existing customer app must be regenerated, checked and published before
+its text changes. Validate the actual generated screens and record every source
+placement's text/link and native checks in the coverage ledger; collection alone
+is not customer acceptance or permission to mark all rows supported.
+
 ### Navigation from top tabs
 
 `navigation-plan.json` records the source navigation kind and the planned target.
@@ -984,6 +1046,43 @@ cannot be inspected: call the builder in your generator and serialize the value
 returns. Run the generator inside the app (after `npm install`), so
 `@wix/himalaya/screens` resolves to the app's own dependency.
 
+### Preserve the template features the source exposes
+
+Treat trimming as a source-feature decision, not a list of screens reached during
+one visitor walkthrough. Before removing a template destination, compare the source
+Account and native widget journeys under the appropriate visitor/member state.
+Keep the supported destination and its data/permission contract when the source
+exposes it. Do not add unrelated verticals merely because the template has them.
+
+| Source feature | Preserve in the generated app |
+| --- | --- |
+| Business identity | Use the collected `business-context.json.displayName` for business identity and bind live chat header/sender/app-info values to the actual business or host state. Preserve the source logo as an image or image binding. Keep the authored app/screen title separate. The technical app slug is an identifier, not a replacement display name. Avoid a global string replacement across source, routes and URLs. |
+| Account Orders and Subscriptions | Retain source-exposed My activity links and their supported `himi_orders` / `himi_my_subscriptions` destinations, including their workers and sign-in/return routing. A visitor gate is not evidence that a member destination should be deleted. Installed services alone do not prove source exposure; compare the source Account. |
+| Programs | Reuse the supported Program card/detail and worker behavior. Preserve access type and the actual login/request/join/pay/Continue action for the visitor or participant state. Do not replace these with an image/title-only card or a generic authenticated Continue. Preserve paid/private policy; do not invoke a live purchase or membership mutation as part of a read-only comparison. |
+| Feed attachments | Reuse the template's rich post card and its `RichContent`/attachment presentation. Preserve inline images, files and their destinations together with text and actions. A text-only replacement is a functional loss even when it can read the post body. |
+
+After applying identity and before claiming completion, run:
+
+```sh
+himi one-app validate-identity --evidence-dir .himi/one-app --content . --json
+```
+
+The command verifies the collected business-name hash, builds the current content,
+and checks emitted screen titles, supported component display fields and the known
+business-chat identity seed for accidental literal slugs. It ignores route IDs,
+URLs and arbitrary API/action values. Exact authored source copy containing the
+slug and a real business whose display name is its slug are preserved. An unrelated
+source page title cannot waive the business-chat identity or its name seed. An older
+collection without a business display name remains unverified; recollect rather
+than editing its evidence or guessing a name.
+
+This is a narrow identity check. It cannot prove every dynamic or translated
+string, branding image, account journey, access policy or attachment is correct.
+Inspect the actual generated descriptors and workers, exercise recorded examples,
+then compare those four source journeys in the real host. Keep their missing
+behavior explicit in coverage and the report. A stock template screenshot or a
+passing identity check cannot substitute for the fresh reconstruction/device pass.
+
 ### Screen-content contract
 
 Use the current [screen design guide](https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md) and the app's
@@ -1108,6 +1207,116 @@ configuration, workers, evidence, screenshots or logs.
 
 ## 4. Verify the reconstructed app and publish its draft
 
+### Check the publish budget before final evidence
+
+Plan for the **8,388,608-byte** publish JSON budget before spending time on final
+screenshots, behavioral runs or native UX records. `.himi` file size and source
+directory totals are different measurements: publication carries JSON-escaped
+descriptors, base64 bundles/assets/icon and the compressed source archive together.
+
+First repoint navigation and retained detail/back-link destinations at the implemented
+generated screens, including destination IDs configured in shared workers. Keep every required
+source journey and its shared destinations in `SPEC.md`'s Screen catalogue, including
+cart, checkout, authentication and detail routes. Inspect a trim plan before applying it:
+
+```sh
+himi template trim --from-spec SPEC.md --links follow --dry-run
+```
+
+Review the retained/removed screens, workers and navigation. Trim only unused template
+definitions that the generated screens replace; `--links follow` can retain linked
+destinations that still matter. Review `workerRefs` and `reparented` results, and preserve
+overflow entries and back navigation instead of accepting their deletion. Do not remove a required vertical or drop its actions
+merely to fit. Apply the same reviewed command without `--dry-run`, then measure:
+
+```sh
+himi publish-size --app <intended-publish-slug> --json
+```
+
+This builds locally using the same release payload, source collector and JSON serializer
+as push. It never looks up an owner, claims a slug or publishes; no credentials or final
+UX/attestation records are required. It can write local build output. It reports
+`bodyBytes`, `limit`, `remainingBytes`, `overageBytes`, source archive bytes and screen/
+bundle counts. Failed static record-ID enumeration, missing declared icons/screens/bundles, unavailable font assets, failed declared widgets
+and failed token snapshots are refused instead of undercounted. The builder's optional
+token absence (404) is reported without inventing token bytes; it does not certify styling.
+The default `reserveBytes` is a **65,536-byte planning allowance** for final metadata;
+`planningBytes` includes it. `--reserve-bytes <n>` changes that allowance.
+
+Measurement uses an isolated contained build: put the intended configuration and
+collected static seed IDs in the package explicitly. Host environment substitutions
+are not its input. A source module that needs host code or live catalog enumeration
+is refused as `build_failed`; materialize the verified source IDs from the collection
+before measuring, or report that prerequisite as blocked. Never swallow that refusal
+and treat missing detail screens as saved bytes.
+
+`bodyBytes` is exact for the stated slug, source-included draft and **no publish metadata**.
+The allowance is not a verified upper bound: final label/notes, evidence and migration
+metadata must fit within the remaining bytes. A changed slug changes both app fields;
+`minimumBodyBytes` uses empty slugs and no metadata as a lower bound. If even that exceeds
+the limit, unknown owner metadata cannot rescue the build. A passing size check is
+conditional on those remaining bytes; the final push still measures its exact envelope
+and runs every evidence gate. The push command has no size-only dry run; use the
+measurement command for probes. Transport compression is not evidence that the current push guard accepts
+an oversized JSON body.
+
+Init-generated `.agents/`, `.claude/` and `HIMALAYA.md` are already excluded by the
+source archive policy shown in `himi push --help`.
+Keep source included; do not work around the budget with `--no-source` or `--force`.
+
+For a large static 8-bit PNG icon, lossless recompression is optional. Keep the original and candidate
+under `.himi/` while checking, use no resize, palette reduction, quantization or lossy
+format, and prove decoded RGBA pixels, dimensions and color profile are unchanged before
+replacing the declared icon. For example, with the optional `sharp` image tool installed
+locally (`npm install --prefix .himi/pixel-tools --no-save --package-lock=false sharp@0.33.5`):
+
+```sh
+node --input-type=module - <declared-icon.png> .himi/icon-lossless.png <<'JS'
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+import { readFileSync, statSync } from 'node:fs';
+const sharp = createRequire(resolve('.himi/pixel-tools/tool.cjs'))('sharp');
+const [input, output] = process.argv.slice(2);
+assert.notEqual(resolve(input), resolve(output), 'preserve the original');
+const beforeMeta = await sharp(input).metadata();
+assert.equal(beforeMeta.format, 'png');
+assert.equal(beforeMeta.depth, 'uchar', 'retain higher-precision originals');
+assert.equal(beforeMeta.pages ?? 1, 1, 'retain animated originals');
+const before = await sharp(input).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+await sharp(input).keepMetadata().png({ compressionLevel: 9, adaptiveFiltering: true, palette: false }).toFile(output);
+const afterMeta = await sharp(output).metadata();
+const after = await sharp(output).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+assert.deepEqual(after.info, before.info);
+assert.deepEqual(afterMeta.icc, beforeMeta.icc);
+assert.equal(afterMeta.orientation ?? 1, beforeMeta.orientation ?? 1);
+assert.ok(after.data.equals(before.data), 'decoded RGBA pixels must match exactly');
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+console.log(JSON.stringify({ pixelsEqual: true, width: after.info.width, height: after.info.height,
+  channels: after.info.channels, beforeBytes: statSync(input).size, afterBytes: statSync(output).size,
+  beforeSHA256: hash(readFileSync(input)), afterSHA256: hash(readFileSync(output)), rgbaSHA256: hash(after.data) }));
+JS
+```
+
+Only copy the candidate over the declared icon if that proof passes and the file is
+smaller. If the tool is unavailable, retain the original and report that optimization
+as unverified. Re-run `himi icon check`, size measurement and affected visual checks
+after replacing it. Save the equality result and original/candidate hashes.
+
+If required journeys still exceed the budget, stop before final evidence and report the
+measured bytes, limit and overage, source archive size, major contributing journeys/
+assets, reviewed trim results, compression/pixel proof, what was tried and what was
+preserved. Attach the numerical output and sanitized manifest/inventory; file sizes can
+explain contributors but never substitute for the assembled measurement. Hand this to
+the migration project owner for the maintained
+[Himalaya issue tracker](https://github.com/wix-private/himalaya/issues) (repository access
+required). If you lack access, return the prepared report to that owner for escalation;
+do not guess a person's contact or claim a hosted preview exists. This step does not
+authorize posting an issue, changing the server limit or publishing.
+
+### Run the final checks
+
 After the source composition and same-site binding are implemented, use the
 existing authoring loop:
 
@@ -1210,9 +1419,8 @@ himi push --draft --target bo
 Keep the editable source archive included. The publish body is limited to 8,388,608
 bytes. It is about base64(source archive + worker bundles + assets + icons) plus the
 descriptor JSON, so a large app can exceed it: one 33-page migration measured
-11,259,935 bytes. Measure early, not at the end: after `himi build`, add up
-`dist/bundles/*`, the icons and a zip of the content directory without the excluded
-paths below. `himi push` refuses an oversized body locally, before it sends anything,
+11,259,935 bytes. Measure early, not at the end, with `himi publish-size` (see
+"Check the publish budget before final evidence"). `himi push` refuses an oversized body locally, before it sends anything,
 with `publish_body_too_large`; its `breakdown`
 gives each part's bytes (`appSource`, `screens`, `bundles`, `assets`, `icon`, `other`)
 and the largest entries by name. Reduce it in this order, and repeat affected

package/guides/one-app-viewer.md

@@ -26,7 +26,7 @@ Two runtime refinements below take precedence over simplified examples in the St
 - Retain source IDs as relationship keys. Give generated files, components, and routes meaningful target names; keep a source-to-target lookup.
 - Do not turn lifecycle or collection metadata into app requirements.
 - The current scope does not introduce unconfigured drawer navigation or independent per-screen header surfaces. Use shared Himi header presentation where appropriate; preserve supplied header/drawer inputs that affect top-bar intent. Record configured behavior that exceeds this target scope as an adaptation or unresolved gap.
-- Retain only `phoneNumber`, `website`, and `services` from the business object, including their permitted nested fields. Do not recover design or titles from excluded business fields.
+- Retain only `phoneNumber`, `website`, and `services` from the business object, including their permitted nested fields, plus the same-site Business `displayName` as business identity only (the current workflow defines its use). Do not recover design or screen titles from other excluded business fields.
 - An unmapped historical catalog row starts a current capability investigation. Implement app-local composition, workers and adapters when feasible. Do not silently drop it, invent different behavior, or substitute a WebView. Escalate only genuine platform-core or access unknowns that prevent the requested reconstruction.
 
 ## Step 1 — Establish the source interpretation
@@ -136,7 +136,7 @@ The source rules below describe the original viewer. **For the current One App m
 Relevant source behavior to preserve when applicable:
 
 - Header definition selects the renderer; a missing definition ID falls back to the detailed header in the inspected domain code.
-- Title and subtitle come from the header domain. Do not silently substitute excluded business-title fields when a dynamic title cannot be resolved from permitted inputs.
+- Title and subtitle come from the header domain. Do not silently substitute excluded business-title fields when a dynamic title cannot be resolved from permitted inputs; the Business `displayName` names the business, not a header or screen title.
 - Detailed-header empty `coverImagesUrls` falls back to global Structure covers for compatibility. Preserve image order and transition timing where configured.
 - `isCollapsible` coordinates the header with the page's scroll container. A static hero image alone does not reproduce collapse behavior.
 - Logo, invite button, CTA, member count/avatars, and business-profile entry point have separate controls. A CTA needs both its configuration and its show flag.

package/guides/sdk-reference.json

@@ -1299,7 +1299,7 @@
         "name": "LinkableScreen",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface LinkableScreen {\n  screenId: string;\n  /** generic <scheme>://screen/<id> route allowed externally? */\n  isPublic: boolean;\n  paramKeys: string[];\n  parentScreenId: string;\n  tabId: string;\n}"
+        "decl": "export interface LinkableScreen {\n  screenId: string;\n  /** generic <scheme>://screen/<id> route allowed externally? */\n  isPublic: boolean;\n  paramKeys: string[];\n  parentScreenId: string;\n  tabId: string;\n  /** #4656 — a signed-in user is required: an external link / push route to this screen while\n   *  signed out presents the sign-in first, then continues to it. Absent ⇒ false. Needs an\n   *  `auth` block (validator warns otherwise). */\n  requiresAuth?: boolean;\n}"
       },
       {
         "name": "SiteNavConfig",
@@ -3714,8 +3714,8 @@
       {
         "name": "MotionSensor",
         "kind": "type",
-        "jsdoc": "/** Which sensor a watch streams. */",
-        "decl": "export type MotionSensor = \"steps\" | \"altitude\" | \"heading\";"
+        "jsdoc": "/** Which sensor (or gesture event) a watch streams. */",
+        "decl": "export type MotionSensor =\n  | \"steps\" | \"altitude\" | \"heading\"\n  | \"accelerometer\" | \"gyroscope\" | \"magnetometer\"\n  | \"shake\" | \"tilt\" | \"significantMotion\";"
       },
       {
         "name": "StepHistoryStatus",
@@ -3727,7 +3727,7 @@
         "name": "MotionAvailability",
         "kind": "interface",
         "jsdoc": "/** What this device can actually do. Never assume — a barometer is common but not universal. */",
-        "decl": "export interface MotionAvailability {\n  /** Pedometer / step counter present (and, on Android, the runtime permission held). */\n  steps: boolean;\n  /** Barometer present. False on simulators and low-end hardware. */\n  altimeter: boolean;\n  /** Magnetometer / compass present. */\n  heading: boolean;\n  /** Whether `getStepCount` can answer a past window — see {@link StepHistoryStatus}. An\n   *  unknown or absent value reads as \"unsupported\", never as \"available\". */\n  stepHistory: StepHistoryStatus;\n}"
+        "decl": "export interface MotionAvailability {\n  /** Pedometer / step counter present (and, on Android, the runtime permission held). */\n  steps: boolean;\n  /** Barometer present. False on simulators and low-end hardware. */\n  altimeter: boolean;\n  /** Magnetometer / compass present. */\n  heading: boolean;\n  /** Whether `getStepCount` can answer a past window — see {@link StepHistoryStatus}. An\n   *  unknown or absent value reads as \"unsupported\", never as \"available\". */\n  stepHistory: StepHistoryStatus;\n  /** Accelerometer present (web: DeviceMotion exists — false on desktop browsers). */\n  accelerometer: boolean;\n  /** Gyroscope present (web: DeviceMotion rotationRate). */\n  gyroscope: boolean;\n  /** Raw magnetometer present. Always false on web — no browser exposes one by default. */\n  magnetometer: boolean;\n  /** Shake events can be detected (needs an accelerometer). */\n  shake: boolean;\n  /** Tilt events can be detected (needs an accelerometer). */\n  tilt: boolean;\n  /** Significant-motion events can be detected (a hardware trigger or an accelerometer). */\n  significantMotion: boolean;\n}"
       },
       {
         "name": "StepSample",
@@ -3751,7 +3751,7 @@
         "name": "MotionSample",
         "kind": "type",
         "jsdoc": "",
-        "decl": "export type MotionSample = StepSample | AltitudeSample | HeadingSample;"
+        "decl": "export type MotionSample =\n  | StepSample | AltitudeSample | HeadingSample\n  /** accelerometer / gyroscope / magnetometer: one raw reading. Units: accelerometer g (gravity\n   *  included; flat face-up ⇒ z ≈ +1 on every platform), gyroscope rad/s, magnetometer µT. */\n  | { x: number; y: number; z: number; timestampMs: number }\n  /** shake: ONE event per shake. `magnitude` is the shake's peak total acceleration, g. */\n  | { magnitude: number; timestampMs: number }\n  /** tilt: attitude relative to gravity, degrees. Flat face-up is { pitch: 0, roll: 0 }; pitch is\n   *  positive when the top edge rises, roll positive when the right edge dips. */\n  | { pitch: number; roll: number; timestampMs: number }\n  /** significantMotion: the device started moving after a period at rest. */\n  | { timestampMs: number };"
       },
       {
         "name": "getPermissionStatus",
@@ -3799,7 +3799,7 @@
         "name": "MotionWatchOptions",
         "kind": "interface",
         "jsdoc": "",
-        "decl": "export interface MotionWatchOptions {\n  /** Which sensor to stream. Defaults to \"steps\". */\n  sensor?: MotionSensor;\n  /** Requested sample interval, ms. The platform treats this as a hint and may deliver\n   *  faster (heading is event-driven) or slower (a step sample needs steps to have happened). */\n  intervalMs?: number;\n  /** Per-poll bridge timeout. Rarely needs changing — see DEFAULT_POLL_TIMEOUT_MS. */\n  pollTimeoutMs?: number;\n}"
+        "decl": "export interface MotionWatchOptions {\n  /** Which sensor to stream. Defaults to \"steps\". */\n  sensor?: MotionSensor;\n  /** Requested sample interval, ms. For the raw sensors (accelerometer / gyroscope /\n   *  magnetometer) it is clamped to 16–1000 ms (default 100) and honoured, subject to the\n   *  60-samples/s ceiling. For steps / altitude / heading the platform treats it as a hint and\n   *  may deliver faster (heading is event-driven) or slower (a step sample needs steps to have\n   *  happened). Ignored by the gesture events, which fire when the gesture happens. */\n  intervalMs?: number;\n  /** Per-poll bridge timeout. Rarely needs changing — see DEFAULT_POLL_TIMEOUT_MS. */\n  pollTimeoutMs?: number;\n}"
       },
       {
         "name": "MotionWatcher",
@@ -3810,7 +3810,7 @@
       {
         "name": "watch",
         "kind": "function",
-        "jsdoc": "/**\n * Open a sensor stream. The native listener starts EAGERLY (not on first iteration), so\n * samples buffer from the moment you call `watch()` even if the consumer iterates late —\n * which matters for steps, where a missed window is lost data rather than a stale value.\n *\n * ```ts\n * // Elevation gain over a hike.\n * let gain = 0, prev: number | undefined;\n * const w = watch({ sensor: \"altitude\", intervalMs: 5000 });\n * for await (const s of w) {\n *   if (prev != null && s.relativeAltitudeM > prev) gain += s.relativeAltitudeM - prev;\n *   prev = s.relativeAltitudeM;\n *   if (done) break;   // break ⇒ auto-stop\n * }\n * ```\n *\n * Type the stream by passing the sample type: `watch<HeadingSample>({ sensor: \"heading\" })`.\n */",
+        "jsdoc": "/**\n * Open a sensor stream. The native listener starts EAGERLY (not on first iteration), so\n * samples buffer from the moment you call `watch()` even if the consumer iterates late —\n * which matters for steps, where a missed window is lost data rather than a stale value.\n *\n * ```ts\n * // Elevation gain over a hike.\n * let gain = 0, prev: number | undefined;\n * const w = watch({ sensor: \"altitude\", intervalMs: 5000 });\n * for await (const s of w) {\n *   if (prev != null && s.relativeAltitudeM > prev) gain += s.relativeAltitudeM - prev;\n *   prev = s.relativeAltitudeM;\n *   if (done) break;   // break ⇒ auto-stop\n * }\n * ```\n *\n * Type the stream by passing the sample type: `watch<HeadingSample>({ sensor: \"heading\" })`.\n *\n * ```ts\n * // Shake to reroll.\n * for await (const _ of watch({ sensor: \"shake\" })) reroll();\n * // Tilt to steer.\n * for await (const t of watch<{ pitch: number; roll: number; timestampMs: number }>({ sensor: \"tilt\" })) steer(t.roll);\n * ```\n */",
         "decl": "export function watch<T extends MotionSample = MotionSample>(options?: MotionWatchOptions): MotionWatcher<T>;"
       },
       {
@@ -3821,6 +3821,43 @@
       }
     ]
   },
+  {
+    "name": "@himalaya/network",
+    "source": "core/sdk/network/src/index.ts",
+    "description": "Tier-5 typed binding for the platform's network capability.",
+    "api": [
+      {
+        "name": "NetworkType",
+        "kind": "type",
+        "jsdoc": "/** What kind of link carries the traffic. `\"none\"` when offline; `\"unknown\"` when the\n *  platform cannot say (most desktop browsers). */",
+        "decl": "export type NetworkType = \"wifi\" | \"cellular\" | \"ethernet\" | \"other\" | \"none\" | \"unknown\";"
+      },
+      {
+        "name": "NetworkStatus",
+        "kind": "interface",
+        "jsdoc": "/** One reading of the device's connectivity. */",
+        "decl": "export interface NetworkStatus {\n  /** The device has a usable network path. */\n  online: boolean;\n  type: NetworkType;\n  /** The link is metered / costly (cellular, a personal hotspot). Best-effort. */\n  expensive: boolean;\n  /** The user asked to save data (iOS Low Data Mode, Android Data Saver, web Save-Data). Best-effort. */\n  constrained: boolean;\n}"
+      },
+      {
+        "name": "normalizeNetworkStatus",
+        "kind": "function",
+        "jsdoc": "/** Coerce whatever crossed the bridge into a well-formed {@link NetworkStatus}. A malformed\n *  or missing field degrades to the honest default rather than throwing. */",
+        "decl": "export function normalizeNetworkStatus(raw: unknown): NetworkStatus;"
+      },
+      {
+        "name": "status",
+        "kind": "function",
+        "jsdoc": "/** Read the current connectivity. */",
+        "decl": "export async function status(): Promise<NetworkStatus>;"
+      },
+      {
+        "name": "subscribe",
+        "kind": "function",
+        "jsdoc": "/**\n * Have `handler` (`\"<service>.<action>\"`) invoked with the new {@link NetworkStatus} on each\n * CHANGE. Changes are debounced 500 ms and a reading equal to the last one delivered is\n * suppressed, so a flapping interface does not storm the reducer. The subscription lives\n * as long as the calling worker and is released when it is torn down. Subscribing the same\n * handler twice is idempotent.\n *\n * Resolves with the status at the moment of subscribing, so the screen can paint the\n * current state without waiting for the first change.\n *\n * ```ts\n * import { subscribe } from \"@himalaya/network\";\n *\n * init: (s) => {\n *   subscribe(\"net.changed\").then((now) => net.changed(now)).catch(() => {});\n *   return s;\n * },\n * changed: (s, status) => ({ ...s, online: status.online, type: status.type }),\n * ```\n */",
+        "decl": "export async function subscribe(handler: string): Promise<NetworkStatus>;"
+      }
+    ]
+  },
   {
     "name": "@himalaya/on-device-ai",
     "source": "core/sdk/on-device-ai/src/index.ts",
@@ -23472,6 +23509,36 @@
         "kind": "function",
         "jsdoc": "/**\n * True when `url` is Wix media that is not PROVABLY bounded below the pixel ceiling\n * the renderers decode at: either dimension missing from the final stage, or either\n * one above `WIX_DETAIL_IMAGE`.\n *\n * Both dimensions are required, and one is genuinely not enough: `fit/w_1400` on a\n * 1400x9000 source derives a 9000px height, so a single stated side proves nothing\n * about the other.\n *\n * This reports the DEFECT. It is deliberately WIDER than what `wixMediaUrl` repairs\n * — the predicate says \"these pixels are not provably bounded\", the rewriter only\n * changes what it can without altering the picture. Four kinds stay flagged after a\n * round-trip:\n *   - an oversized `crop` — NOT rewritten; moving `w_`/`h_` selects a different\n *     source rectangle, so it needs a human to pick a smaller crop;\n *   - EITHER mode stating one dimension — IS rewritten (that side gets bounded, and\n *     one side is not a box, so nothing is re-cropped), but the derived side still\n *     cannot be proven, so it remains flagged;\n *   - a CHAINED transform (`crop/…/fill/…`) — this predicate reads its final stage,\n *     but `WIX_TRANSFORM` matches a single stage, so `wixMediaUrl` returns it\n *     verbatim. A chained url above the ceiling is therefore reported and not\n *     repaired. Rewriting the last stage of a chain is a deliberate follow-up: it\n *     is the media manager's own output shape, so it is worth having, and it is\n *     more parsing than this change should carry.\n *\n * NOTE: `tools/ci/lint-wix-media-sizing.mjs` does not call this today — it matches\n * hand-built url construction in worker SOURCE, which is a different (static) check.\n * Wiring a runtime gate to this predicate is tracked separately.\n */",
         "decl": "export function isUnsizedWixMedia(url: string): boolean;"
+      },
+      {
+        "name": "ImageTarget",
+        "kind": "interface",
+        "jsdoc": "/** Pure rendition policy shared by web/RN. Native mirrors use the same request fixtures. */",
+        "decl": "export interface ImageTarget {\n  width: number;\n  height: number;\n  scale: number;\n  mode?: string;\n  maxEdge?: number;\n}"
+      },
+      {
+        "name": "imagePixelSize",
+        "kind": "function",
+        "jsdoc": "/**\n * The pixel size an image is requested at for a box of `width`×`height` points at `scale`: the box in pixels,\n * its longer edge rounded up to a shared bucket (96 … 1400, or up to `maxEdge`, at most 4096) so nearby sizes\n * share one cached rendition. A size it returns maps to itself. An invalid box asks for `maxEdge` square.\n */",
+        "decl": "export function imagePixelSize(width: number, height: number, scale: number, maxEdge = 1400);"
+      },
+      {
+        "name": "resolveImageRendition",
+        "kind": "function",
+        "jsdoc": "/** Keep the caller's source untouched: this URL belongs to a display request, not entity data. */",
+        "decl": "export function resolveImageRendition(source: string, target: ImageTarget);"
+      },
+      {
+        "name": "ImageCandidate",
+        "kind": "interface",
+        "jsdoc": "",
+        "decl": "export interface ImageCandidate { url: string; width: number; height: number }"
+      },
+      {
+        "name": "imageCandidates",
+        "kind": "function",
+        "jsdoc": "/**\n * The renditions a renderer offers for one image, smallest first, so the HOST picks among them by\n * its own layout and pixel density (web `srcset`, a React Native `source` array) with no\n * measurement code of ours. A fixed box gets one candidate per screen density; a fluid one (no\n * numeric width) gets fluid widths, its height from `ratio` when known. A source that cannot be\n * resized safely yields exactly itself.\n */",
+        "decl": "export function imageCandidates(\n  source: string,\n  box: { width?: number; height?: number; ratio?: number; mode?: string },\n  scales: number[] = [1, 2, 3],\n): ImageCandidate[];"
       }
     ]
   },

package/guides/tier-5-add-a-screen.md

@@ -660,6 +660,38 @@ linkableScreens: [
 ],
 ```
 
+**A screen only a signed-in user should open** — an order, an account page, an invite — sets
+`requiresAuth: true` on its linkable entry:
+
+```ts
+{ screenId: "order", isPublic: true, paramKeys: ["id"], parentScreenId: "orders", tabId: "account", requiresAuth: true },
+```
+
+An external link to it — custom scheme, universal/app link, push route — while signed out does
+not open it anonymously. The native `DeepLinkCoordinator` holds the link, waits for the gate's
+silent bootstrap (a restored session goes straight through, with no prompt), then presents the
+app's sign-in cover (its `gateScreenId` when set). Signing in applies the held link unchanged —
+tab, parent chain, params; cancelling lands on the target's tab root and drops the link
+(`nav_verb_dropped` / `auth_cancelled`). A second link while the sign-in is up replaces the first.
+Signed in, or `requiresAuth` unset: nothing changes. The flag needs an `auth` block — without one
+there is no sign-in to present, the link opens as before, and serving the app's config logs a
+warning. iOS and Android; the macOS coordinator honours it too, but no macOS shell binds a sign-in
+gate today, so on macOS the flag is inert until a Mac shell sets `authGate`. The web host does not hold links yet. In-app navigation (`himi.open`,
+`_nav`) is not gated: a screen the app itself opens is the app's own business.
+
+A shell gets this through core: the coordinator asks the gate the shell's `AuthGateRoot` /
+`AuthSignInCover` bound. Three things are the shell's:
+
+- **Read the live config.** Build the coordinator with `configProvider:` (read at every apply),
+  not a `config:` snapshot — a snapshot taken before the OTA config is cached (a clean install)
+  has no linkables, so no `requiresAuth` either.
+- **Bind the gate early.** A shell that can receive a link before that root has drawn (a cold
+  start) sets `coordinator.authGate = <its SessionGate>` where it builds the coordinator.
+- **Mark the bootstrap.** Call `sessionGate.markSilentBootstrapSettled()` once its
+  `provider.bootstrap()` returns. Until then a held link waits (a provider not bound yet is
+  waited for too, never read as "no auth"); a shell that never marks it waits a short grace
+  (3 s) before presenting the sign-in.
+
 **3. The detail worker reads `himalaya.input.id`** and loads in module-eval `load()`
 (the blessed initial-load primitive above), **not** an `onAppear` action — `onAppear`
 fires on every platform, but it is a mount hook, not the initial-load path (see the

package/guides/web-page-sdk-reference.md

@@ -37,6 +37,7 @@ the SDK sources, so it matches the shipped SDKs.
 - [`location`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Flocation?format=md) — Device location. 10 methods.
 - [`media_playback`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fmedia_playback?format=md) — Background-capable media playback and offline downloads. 21 methods · returns FileHandles.
 - [`motion`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fmotion?format=md) — Device's motion sensors. 7 methods.
+- [`network`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fnetwork?format=md) — Network capability. 1 method.
 - [`on_device_ai`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fon_device_ai?format=md) — ON-DEVICE text generation. 4 methods.
 - [`open_url`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fopen_url?format=md) — Opening links + external apps. 2 methods.
 - [`pdf`](https://apps.wix.com/_api/himi-serve/authoring/resource/web-sdk%2Fpdf?format=md) — Viewing PDF documents. 2 methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1579.0",
+  "version": "0.1581.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": [
@@ -34,6 +34,7 @@
     "test": "node ../../tools/ci/run-tests.mjs --package tools/himi-cli --"
   },
   "dependencies": {
+    "@jitl/quickjs-wasmfile-release-sync": "^0.32.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "@rive-app/canvas": "2.38.3",
     "ajv": "^8.17.1",
@@ -71,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "939c5230409902d493ec5b28c46a83496669032bc8f663eabd42dcf6"
+  "falconPackageHash": "64fa52bfc77be18b169f50cc51f1c41e5a323d05cc64bbf39c166dbf"
 }