@shipvo/sim 0.1.5 → 0.1.6

package/apps.mjs

@@ -0,0 +1,138 @@
+// Installed apps on the simulated phone: state, the phone.json profile, and the Store screen. Pure: no DOM, no timers.
+// The server uses these rules for the MCP tools install_app, uninstall_app and switch_app. The frame page uses the same
+// functions (serialised into the page) to draw the home screen icons and the Store. Our own artwork: no vendor marks.
+import { SETTINGS, settingPatch } from "./settings.mjs";
+
+/** Typed error: unknown_app, already_installed, not_installed or bad_profile. */
+export class AppsError extends Error { constructor(code, message) { super(message); this.code = code; } }
+
+/** The apps the Store lists when there is no network or no marketplace. Used by tests and offline runs. */
+export const STORE_FIXTURE = [
+  { id: "tide", name: "Tide & Tackle", url: "fixture://tide", version: "1.0.0" },
+  { id: "notes", name: "Pocket Notes", url: "fixture://notes", version: "0.3.1" },
+  { id: "weather", name: "Harbour Weather", url: "fixture://weather", version: "2.1.0" },
+];
+
+const text = (v, n) => String(v ?? "").replace(/[<>"'\\]/g, "").slice(0, n);
+const entry = (a) => ({ id: text(a.id, 60), name: text(a.name || a.id, 40), url: String(a.url ?? ""), version: text(a.version ?? "0.0.0", 20) });
+
+/** Phone state for apps. `installed_apps` is a list of { id, name, url, version }; `current_app` is an id or null (the app the phone was started with). */
+export function createApps(profile = {}) {
+  return { installed_apps: [], current_app: null, store: STORE_FIXTURE.map(entry), settings: {}, log: [], ...profile };
+}
+
+/**
+ * Parse a phone.json profile: { "apps": [{id,name,url?,version?}], "current_app"?: id, "settings"?: { dark_mode: true, ... }, "store"?: [...] }.
+ * The same profile always gives the same phone. Throws AppsError("bad_profile") with the reason. Contacts and photos come later.
+ */
+export function loadProfile(json) {
+  let p = json;
+  if (typeof json === "string") { try { p = JSON.parse(json); } catch { throw new AppsError("bad_profile", "phone.json is not valid JSON"); } }
+  if (!p || typeof p !== "object" || Array.isArray(p)) throw new AppsError("bad_profile", "phone.json must be an object");
+  const apps = p.apps ?? [];
+  if (!Array.isArray(apps)) throw new AppsError("bad_profile", "'apps' must be a list");
+  const st = createApps();
+  if (p.store !== undefined) { if (!Array.isArray(p.store)) throw new AppsError("bad_profile", "'store' must be a list"); st.store = p.store.map((a) => entry(a)); }
+  const seen = new Set();
+  for (const a of apps) {
+    if (!a || typeof a.id !== "string" || !/^[a-z0-9-]+$/.test(a.id)) throw new AppsError("bad_profile", "every app needs an id of lowercase letters, digits and dashes");
+    if (seen.has(a.id)) throw new AppsError("bad_profile", `app '${a.id}' is listed twice`);
+    seen.add(a.id); st.installed_apps.push(entry(a));
+  }
+  if (p.current_app != null) { if (!seen.has(p.current_app)) throw new AppsError("bad_profile", `current_app '${p.current_app}' is not in 'apps'`); st.current_app = p.current_app; }
+  if (p.settings !== undefined) {
+    if (!p.settings || typeof p.settings !== "object") throw new AppsError("bad_profile", "'settings' must be an object");
+    for (const [k, v] of Object.entries(p.settings)) { try { settingPatch(k, v); } catch (e) { throw new AppsError("bad_profile", `settings: ${e.message}`); } st.settings[k] = v; }
+  }
+  return st;
+}
+
+/** The device patch that applies a profile's settings (the same for every run). */
+export function profilePatch(st) {
+  return Object.assign({}, ...Object.entries(st.settings).map(([k, v]) => settingPatch(k, v)));
+}
+
+const note = (st, name, id) => { st.log.push({ at: Date.now(), name, app: id, source: "simulated" }); };
+
+/** Install an app from the catalog (default: the phone's Store list). Throws unknown_app or already_installed. */
+export function installApp(st, id, catalog = st.store) {
+  const found = (catalog ?? []).find((a) => a.id === id);
+  if (!found) throw new AppsError("unknown_app", `no app '${id}' in the Store. Apps: ${(catalog ?? []).map((a) => a.id).join(", ") || "none"}`);
+  if (st.installed_apps.some((a) => a.id === id)) throw new AppsError("already_installed", `'${id}' is already installed`);
+  st.installed_apps.push(entry(found)); note(st, "install_app", id); return st;
+}
+
+/** Remove an app. If it was in front, the phone goes home and current_app is empty. Throws not_installed. */
+export function uninstallApp(st, id, nav) {
+  if (!st.installed_apps.some((a) => a.id === id)) throw new AppsError("not_installed", `'${id}' is not installed`);
+  st.installed_apps = st.installed_apps.filter((a) => a.id !== id);
+  if (st.current_app === id) { st.current_app = null; if (nav) nav.where = "home"; }
+  note(st, "uninstall_app", id); return st;
+}
+
+/** Open an installed app (tap its icon). Throws not_installed. */
+export function switchApp(st, id, nav) {
+  if (!st.installed_apps.some((a) => a.id === id)) throw new AppsError("not_installed", `'${id}' is not installed`);
+  st.current_app = id; if (nav) nav.where = "app"; note(st, "switch_app", id); return st;
+}
+
+/** Plain text for an agent: the installed apps, then the Store. */
+export function describeApps(st) {
+  const l = ["Installed apps"];
+  if (!st.installed_apps.length) l.push("- none");
+  for (const a of st.installed_apps) l.push(`- button "${a.name}" (${a.id} ${a.version}${st.current_app === a.id ? ", open" : ""}: switch_app opens it)`);
+  l.push("Store");
+  for (const a of st.store) l.push(st.installed_apps.some((i) => i.id === a.id) ? `- "${a.name}" (${a.id}): installed` : `- button "Install ${a.name}" (${a.id}: install_app installs it)`);
+  return l.join("\n");
+}
+
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
+/** Home screen icons for installed apps. */
+export function installedIconsHtml(st) {
+  return st.installed_apps.map((a) => `<button type="button" class="sf-icon sf-appicon" data-part="installed-app" data-app="${esc(a.id)}" aria-label="${esc(a.name)}"><b>${esc(a.name.slice(0, 1).toUpperCase())}</b><span>${esc(a.name)}</span></button>`).join("");
+}
+/** Store rows: one button per app that is not installed yet. */
+export function storeRowsHtml(st) {
+  return st.store.map((a) => {
+    const have = st.installed_apps.some((i) => i.id === a.id);
+    return `<div class="sf-store-row" data-app="${esc(a.id)}"><span class="sf-store-name">${esc(a.name)} <small>${esc(a.version)}</small></span>${have ? `<span class="sf-store-have">Installed</span>` : `<button type="button" data-part="store-install" data-app="${esc(a.id)}" aria-label="Install ${esc(a.name)}">Install</button>`}</div>`;
+  }).join("");
+}
+
+/** The Store icon for the home screen and the Store screen. Hidden until opened. */
+export function storeIconHtml() {
+  return `<button type="button" class="sf-icon" data-part="store-icon" aria-label="Store" style="left:220px"><b>▤</b><span>Store</span></button>`;
+}
+export function storeScreenHtml() {
+  return `<div class="sf-settings sf-store" data-part="store-screen" role="dialog" aria-label="Store" tabindex="-1" hidden><h2 class="sf-sh">Store</h2><div data-part="store-rows" role="list" aria-label="Apps"></div><button type="button" class="sf-close" data-part="store-close">Close</button></div>`;
+}
+export const storeCss = [
+  `.sf-store{position:absolute;inset:0;z-index:8;overflow:auto;padding:70px 20px 40px;box-sizing:border-box;background:#0b1320;color:#fff;font-family:system-ui,sans-serif}[data-theme="light"] .sf-store{background:#f4f7fb;color:#111}`,
+  `.sf-store[hidden]{display:none}.sf-store-row{display:flex;justify-content:space-between;align-items:center;padding:12px 0;border-bottom:1px solid #8883;font:600 15px system-ui,sans-serif}.sf-store-row small{opacity:.6;font-weight:400}`,
+  `.sf-store-row button,.sf-store .sf-close{border:0;border-radius:999px;padding:12px 18px;min-height:44px;background:#f4a261;color:#102030;font:600 14px system-ui,sans-serif;cursor:pointer}.sf-store-have{color:#8a94a6;font-size:13px}[data-theme="light"] .sf-store-have{color:#4a5568}.sf-store .sf-close{margin-top:18px;background:#8883;color:inherit}`,
+  `.sf-apps{position:absolute;left:28px;right:28px;top:180px;display:flex;flex-wrap:wrap;gap:20px 24px}.sf-apps .sf-icon{position:static}`,
+].join("");
+
+/** Client script: draws installed icons and the Store in the frame page. `seed` is a phone.json object. */
+export function appsClientScript(iframeId = "app", seed = {}) {
+  return `(function(){
+var AppsError=function(c,m){var e=new Error(m);e.code=c;return e},STORE_FIXTURE=${JSON.stringify(STORE_FIXTURE)};
+var entry=${entry.toString()},text=${text.toString()},esc=${esc.toString()},note=${note.toString()},installApp=${installApp.toString()},switchApp=${switchApp.toString()},installedIconsHtml=${installedIconsHtml.toString()},storeRowsHtml=${storeRowsHtml.toString()},createApps=${createApps.toString()};
+var loadProfile=${loadProfile.toString()},settingPatch=function(){};
+var r=document.querySelector('[data-part="phone-body"]');if(!r)return;
+var q=function(p){return r.querySelector('[data-part="'+p+'"]')},sc=q("store-screen"),home=q("home-screen");if(!sc||!home)return;
+var st;try{st=loadProfile(${JSON.stringify(seed)})}catch(x){st=createApps()}
+st.settings={};
+var box=document.createElement("div");box.className="sf-apps";box.setAttribute("data-part","installed-apps");home.appendChild(box);
+function drawHome(){box.innerHTML=installedIconsHtml(st)}
+function drawStore(){q("store-rows").innerHTML=storeRowsHtml(st)}
+function open(on){sc.hidden=!on;if(on){drawStore();sc.focus({preventScroll:true})}}
+drawHome();
+r.addEventListener("click",function(e){var t=e.target;if(!t.closest)return;
+if(t.closest('[data-part="store-icon"]'))return open(true);
+if(t.closest('[data-part="store-close"]'))return open(false);
+var i=t.closest('[data-part="store-install"]');if(i){try{installApp(st,i.getAttribute("data-app"))}catch(x){}drawStore();drawHome();return}
+var a=t.closest('[data-part="installed-app"]');if(a){try{switchApp(st,a.getAttribute("data-app"))}catch(x){}window.postMessage({type:"pn:nav",where:"app"},"*")}});
+document.addEventListener("keydown",function(e){if(e.key==="Escape"&&!sc.hidden)open(false)});
+})();`;
+}

package/browser-app.mjs

@@ -0,0 +1,83 @@
+// The Browser app of Shipvo Phone, drawn inside the phone body. Android style: controls on top, like a Chrome tab bar.
+// iPhone style: address pill on top, toolbar at the bottom. The page below is the live view of the phone's Chromium:
+// frames come over a WebSocket, taps, swipes and typing go back as input. Our own artwork, no vendor icons.
+import { renderFrame } from "./frame.mjs";
+
+const I = {
+  back: '<path d="M15 5l-7 7 7 7" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>',
+  forward: '<path d="M9 5l7 7-7 7" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>',
+  reload: '<path d="M19 12a7 7 0 1 1-2.2-5.1M19 4v4.5h-4.5" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>',
+};
+const btn = (part, label, body) => `<button type="button" class="ba-btn" data-part="${part}" aria-label="${label}"><svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true">${body}</svg></button>`;
+const tabsBtn = '<button type="button" class="ba-btn ba-tabs" data-part="tabs" aria-label="Tabs"><span data-part="tab-count">1</span></button>';
+const url = '<form class="ba-url" data-part="address-form"><input data-part="address" aria-label="Address" inputmode="url" autocomplete="off" autocapitalize="off" spellcheck="false" placeholder="Search or type a URL"></form>';
+
+/** The markup and CSS of the Browser app for one skin. */
+export function renderBrowserApp(skin = "android") {
+  const nav = btn("back", "Back", I.back) + btn("forward", "Forward", I.forward) + btn("reload", "Reload", I.reload);
+  const ios = skin === "ios";
+  const html = `<div class="ba" data-part="browser-app" data-skin="${skin}">`
+    + (ios ? `<div class="ba-top">${url}</div>` : `<div class="ba-top">${nav}${url}${tabsBtn}</div>`)
+    + `<div class="ba-view" tabindex="0" data-part="browser-view"><img data-part="screen" alt="Web page" draggable="false"><p class="ba-empty" data-part="empty">No page open</p><p class="ba-toast" data-part="toast" role="status" hidden></p></div>`
+    + (ios ? `<div class="ba-bottom">${nav}${tabsBtn}</div>` : "")
+    + `<div class="ba-sheet" data-part="tab-list" hidden><ul></ul><button type="button" data-part="new-tab">New tab</button></div></div>`;
+  const css = [
+    `.ba{--ba-bg:#fff;--ba-fg:#111;--ba-bar:${ios ? "#f2f2f7" : "#f1f3f4"};--ba-field:${ios ? "#e3e3e8" : "#fff"};--ba-icon:${ios ? "#0a64d6" : "#444"};--ba-line:#d0d0d5;--ba-muted:#595959;--ba-card:#eee;--ba-sheet:#fffe;--ba-focus:#0a64d6;--ba-toast:#222;--ba-toast-fg:#fff}`,
+    `@media (prefers-color-scheme:dark){.ba{--ba-bg:#121212;--ba-fg:#f1f1f1;--ba-bar:${ios ? "#1c1c1e" : "#202124"};--ba-field:${ios ? "#2c2c2e" : "#303134"};--ba-icon:${ios ? "#5eb0ff" : "#d0d0d0"};--ba-line:#3a3a3c;--ba-muted:#b0b0b0;--ba-card:#2a2a2c;--ba-sheet:#121212ee;--ba-focus:#8ab4f8;--ba-toast:#f1f1f1;--ba-toast-fg:#111}}`,
+    `.ba{position:absolute;inset:0;display:flex;flex-direction:column;background:var(--ba-bg);color:var(--ba-fg);font:14px system-ui,sans-serif}`,
+    `.ba button:focus-visible,.ba input:focus-visible,.ba-view:focus-visible{outline:3px solid var(--ba-focus);outline-offset:-3px}`,
+    `.ba-top,.ba-bottom{flex:none;display:flex;align-items:center;gap:4px;padding:${ios ? "6px 16px" : "6px 8px"};background:var(--ba-bar)}`,
+    `.ba-bottom{justify-content:space-around;padding:6px 10px 4px;border-top:1px solid var(--ba-line)}`,
+    `.ba-btn{flex:none;width:40px;height:40px;border:0;border-radius:${ios ? "10px" : "50%"};background:transparent;color:var(--ba-icon);display:flex;align-items:center;justify-content:center;cursor:pointer}`,
+    `.ba-tabs span{display:block;min-width:20px;padding:1px 3px;box-sizing:border-box;border:2px solid currentColor;border-radius:${ios ? "5px" : "6px"};font:700 12px system-ui,sans-serif;text-align:center}`,
+    `.ba-url{flex:1;min-width:0}.ba-url input{width:100%;box-sizing:border-box;height:38px;border:0;border-radius:${ios ? "10px" : "19px"};padding:0 14px;background:var(--ba-field);font:15px system-ui,sans-serif;color:var(--ba-fg);${ios ? "text-align:center" : ""}}`,
+    // The page keeps its own aspect ratio: contain letterboxes it, and pointer positions are mapped against the drawn image.
+    `.ba-view{flex:1;min-height:0;position:relative;background:var(--ba-bg);overflow:hidden}.ba-view img{display:block;width:100%;height:100%;object-fit:contain;touch-action:none;user-select:none;-webkit-user-drag:none}.ba-view img:not([src]){display:none}`,
+    `.ba-empty{position:absolute;inset:0;margin:0;display:flex;align-items:center;justify-content:center;color:var(--ba-muted)}.ba-view.has-frame .ba-empty{display:none}`,
+    `.ba-toast{position:absolute;left:12px;right:12px;bottom:12px;margin:0;padding:10px 14px;border-radius:12px;background:var(--ba-toast);color:var(--ba-toast-fg)}.ba-toast[hidden],.ba-sheet[hidden]{display:none}`,
+    `.ba-sheet{position:absolute;inset:0;background:var(--ba-sheet);padding:12px;overflow:auto}.ba-sheet ul{list-style:none;margin:0 0 10px;padding:0}.ba-sheet li{display:flex;gap:8px;align-items:center;padding:2px 2px 2px 10px;margin-bottom:6px;border-radius:12px;background:var(--ba-card)}.ba-sheet li[aria-current=true]{outline:2px solid var(--ba-focus)}`,
+    `.ba-sheet button{min-height:44px;border:0;border-radius:10px;background:none;color:inherit;font:inherit;cursor:pointer}.ba-sheet li .pick{flex:1;min-width:0;text-align:left;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.ba-sheet li .close{min-width:44px;font-size:22px}.ba-sheet>button{padding:0 14px;background:var(--ba-card)}`,
+  ].join("\n");
+  return { html, css };
+}
+
+/** Browser script for the page that holds the app. `session` names the sim session whose Chromium it shows. */
+export function browserAppScript(session) {
+  return `(function(){
+var $=function(p){return document.querySelector('[data-part="'+p+'"]')},img=$("screen"),view=$("browser-view"),vw=393,vh=851,ws,st={tabs:[]};
+function send(m){if(ws&&ws.readyState===1)ws.send(JSON.stringify(m))}
+function toast(t){var e=$("toast");e.textContent=t;e.hidden=false;clearTimeout(toast.t);toast.t=setTimeout(function(){e.hidden=true},3500)}
+function draw(){var a=$("address");if(document.activeElement!==a){var t=st.tabs.filter(function(x){return x.active})[0];a.value=st.url&&st.url!=="about:blank"?st.url:""}
+$("tab-count").textContent=st.tabs.length||1;
+var l=$("tab-list").querySelector("ul");l.innerHTML="";st.tabs.forEach(function(t){var li=document.createElement("li");if(t.active)li.setAttribute("aria-current","true");
+var b=document.createElement("button");b.className="pick";b.textContent=t.title||t.url||"New tab";b.onclick=function(){send({type:"tab",index:t.index});$("tab-list").hidden=true};
+var x=document.createElement("button");x.className="close";x.textContent="\\u00d7";x.setAttribute("aria-label","Close tab");x.onclick=function(){send({type:"closetab",index:t.index})};li.append(b,x);l.append(li)})}
+function connect(){ws=new WebSocket((location.protocol==="https:"?"wss://":"ws://")+location.host+"/browser/ws?session="+encodeURIComponent(${JSON.stringify(session)}));
+ws.onmessage=function(e){var m=JSON.parse(e.data);
+if(m.type==="frame"){vw=m.width||vw;vh=m.height||vh;img.src="data:image/jpeg;base64,"+m.data;view.classList.add("has-frame")}
+else if(m.type==="state"){st=m;draw()}
+else if(m.type==="browser"){toast("Opened in Browser: "+m.url)}
+else if(m.type==="app"){toast("Opened in the app: "+m.url);window.dispatchEvent(new CustomEvent("shipvo:open-app",{detail:m.url}))}
+else if(m.type==="error")toast(m.message)};
+ws.onclose=function(){setTimeout(connect,1000)}}
+connect();
+function pt(e){var r=img.getBoundingClientRect(),k=Math.min(r.width/vw,r.height/vh),ox=r.left+(r.width-vw*k)/2,oy=r.top+(r.height-vh*k)/2;
+return{x:Math.max(0,Math.min(vw,(e.clientX-ox)/k)),y:Math.max(0,Math.min(vh,(e.clientY-oy)/k))}}
+var down=null;
+img.addEventListener("pointerdown",function(e){down=pt(e);view.focus();e.preventDefault()});
+img.addEventListener("pointerup",function(e){if(!down)return;var u=pt(e),d=Math.hypot(u.x-down.x,u.y-down.y);
+send(d<10?{type:"tap",x:down.x,y:down.y}:{type:"swipe",x1:down.x,y1:down.y,x2:u.x,y2:u.y});down=null});
+view.addEventListener("keydown",function(e){if(e.key==="Enter"||e.key==="Backspace"||e.key==="Tab"){e.preventDefault();send({type:"key",key:e.key})}
+else if(e.key.length===1&&!e.ctrlKey&&!e.metaKey){e.preventDefault();send({type:"text",text:e.key})}});
+$("back").onclick=function(){send({type:"back"})};$("forward").onclick=function(){send({type:"forward"})};$("reload").onclick=function(){send({type:"reload"})};
+$("tabs").onclick=function(){var t=$("tab-list");t.hidden=!t.hidden};$("new-tab").onclick=function(){send({type:"newtab"});$("tab-list").hidden=true};
+$("address-form").onsubmit=function(e){e.preventDefault();var v=$("address").value.trim();if(!v)return;if(!/^[a-z][a-z0-9+.-]*:/i.test(v))v="https://"+v;send({type:"open",url:v});$("address").blur()};
+})();`;
+}
+
+/** A full page: the phone body in the given skin with the Browser app in it. */
+export function browserAppPage(skin, session) {
+  const app = renderBrowserApp(skin), frame = renderFrame({ skin, screen: app.html });
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>Browser (simulated ${skin === "ios" ? "iPhone" : "Android"})</title>
+<style>html,body{margin:0;height:100%;background:#e8eaed;overflow:hidden}body{display:flex;align-items:center;justify-content:center}${frame.css}\n${app.css}</style></head><body>${frame.html}<script>${browserAppScript(session).replace(/<\/script/gi, "<\\/script")}</script></body></html>`;
+}

package/frame.d.mts

@@ -11,7 +11,7 @@ export type FrameStatus = {
   /** Level 0 to 100, or an object. Default 100. */
   battery?: number | { level?: number; charging?: boolean };
 };
-export type FrameOptions = { skin?: FrameSkin; dark?: boolean; status?: FrameStatus; /** HTML for the screen area. */ screen?: string };
+export type FrameOptions = { skin?: FrameSkin; dark?: boolean; status?: FrameStatus; /** HTML for the screen area. */ screen?: string; /** Draw Lumi beside the cutout. Default: on, off in CI; SHIPVO_LUMI=off|on overrides. */ lumi?: boolean; /** Also draw Lumi's first-run guide. Needs lumi. Default: off. */ guide?: boolean };
 export type Frame = {
   skin: FrameSkin;
   /** Screen size in CSS pixels. */
@@ -34,4 +34,7 @@ export function isDarkBackground(color: string): boolean;
 /** The clock text and icons markup, for redrawing the status bar. */
 export function statusParts(status?: FrameStatus): { time: string; icons: string };
 /** Browser script that keeps the status bar live from the app's `pn:status` events. */
-export function statusClientScript(iframeId?: string, skin?: FrameSkin): string;
+export function statusClientScript(iframeId?: string, skin?: FrameSkin, phone?: object): string;
+
+export type LumiState = "idle" | "working" | "happy" | "worried";
+export type LumiEvent = { kind: "check-passed" | "flow-done" | "page-error" | "crash" | "action-failed" | "check-failed"; name?: string; error?: unknown; detail?: unknown };

package/frame.mjs

@@ -3,6 +3,13 @@
 // Scaling to fit the window is done by the page with a CSS transform on the element this markup sits in.
 
 import { lockScreenHtml, bootScreenHtml, offScreenHtml } from "./lifecycle.mjs";
+import { shadeHtml, shadeCss, shadeClientScript } from "./shade.mjs";
+import { settingsHtml, settingsIconHtml, settingsCss, settingsClientScript } from "./settings.mjs";
+import { storeIconHtml, storeScreenHtml, storeCss, appsClientScript } from "./apps.mjs";
+import { updateBannerHtml, updateCss, updateClientScript } from "./update.mjs";
+import { lumiHtml, lumiCaptionHtml, lumiCss, lumiClientScript, lumiDefault } from "./lumi.mjs";
+import { guideHtml, guideCss, guideClientScript } from "./guide.mjs";
+import { homeScreenHtml, recentsHtml, navButtonsHtml, navScreensCss, classifySwipe, setVisibilityInPage } from "./nav.mjs";
 
 export const SKINS = {
   android: { label: "Android", width: 412, height: 915, radius: 36, bezel: 10, status: 36, bar: 24, pad: 22, indicator: 108, part: "punch-hole", bottom: "gesture-bar" },
@@ -30,9 +37,9 @@ export function normalizeStatus(status = {}) {
 /** Maps the simulated device ({ online, airplane, battery } from @shipvo/device) and a clock to a status object. Network off shows no signal and no wifi. */
 export function statusFromDevice(device = {}, now = new Date()) {
   const d = device && typeof device === "object" ? device : {};
-  const online = d.online !== false && d.airplane !== true;
+  const online = d.online !== false && d.airplane !== true && (d.wifi !== false || d.mobileData !== false);
   const h = now.getHours() % 12 || 12, m = String(now.getMinutes()).padStart(2, "0");
-  return { time: `${h}:${m}`, signal: online ? 4 : 0, wifi: online, airplane: d.airplane === true, battery: d.battery };
+  return { time: `${h}:${m}`, signal: online && d.mobileData !== false ? 4 : 0, wifi: online && d.wifi !== false, airplane: d.airplane === true, battery: d.battery };
 }
 
 /** True when a CSS colour (#rgb, #rrggbb, rgb(), rgba()) is dark, so the status text should be light. Unknown or transparent colours count as light. */
@@ -57,7 +64,7 @@ export function statusParts(status) {
  * airplane or battery change), redraws the status bar, ticks the clock each minute and flips the text colour from the app's top background.
  * `iframeId` is the app iframe. It expects the markup from renderFrame and the functions below inlined by this script.
  */
-export function statusClientScript(iframeId = "app", skin = "android") {
+export function statusClientScript(iframeId = "app", skin = "android", phone = {}) {
   return `(function(){
 var statusParts=${statusParts.toString()},normalizeStatus=${normalizeStatus.toString()},icons=${icons.toString()},battery=${battery.toString()},svg=${svg.toString()},isDarkBackground=${isDarkBackground.toString()},statusFromDevice=${statusFromDevice.toString()};
 var clean=${clean.toString()},clamp=${clamp.toString()};
@@ -70,8 +77,8 @@ while(e){var c=w.getComputedStyle(e).backgroundColor;if(c&&c!=="transparent"&&!/
 function theme(w){var r=root();if(!r)return;var c=topColor(w),dark=isDarkBackground(c);
 r.setAttribute("data-theme",dark?"dark":"light");r.style.setProperty("--sf-status-fg",dark?"#fff":"#111");r.style.setProperty("--sf-status-bg",c)}
 function hook(){var f=document.getElementById(${JSON.stringify(iframeId)});var w=f&&f.contentWindow;if(!w)return;
-if(w.__pnDevice&&w.__pnDevice.status)dev=w.__pnDevice.status();draw();theme(w);
-if(!w.__shipvoStatusHooked){w.__shipvoStatusHooked=true;w.addEventListener("pn:status",function(e){dev=e.detail;draw();theme(w)})}}
+if(w.__pnDevice&&w.__pnDevice.status)dev=Object.assign({},w.__pnDevice.status(),w.__pnDevice.settings?w.__pnDevice.settings():{});draw();theme(w);
+if(!w.__shipvoStatusHooked){w.__shipvoStatusHooked=true;w.addEventListener("pn:status",function(e){dev=Object.assign({},dev,e.detail);draw();theme(w)});w.addEventListener("pn:settings",function(e){dev=Object.assign({},dev,e.detail);draw()})}}
 var f=document.getElementById(${JSON.stringify(iframeId)});if(f){f.addEventListener("load",hook);hook()}
 (function buttons(){var r=root();if(!r)return;var q=function(p){return r.querySelector('[data-part="'+p+'"]')},vol=50,hold,volT,bootT;
 if(!q("power-button")||!q("lock-screen")||!q("power-menu"))return;
@@ -99,15 +106,53 @@ if(e.detail===0&&e.shiftKey){shown("power-menu")?closeMenu():openMenu();return}
 if(shown("power-menu")){closeMenu();return}
 if(shown("lock-screen")){return}
 lockNow()});
-function bump(d){vol=Math.max(0,Math.min(100,vol+d));q("volume-level").textContent=vol;show(q("volume-overlay"),true);clearTimeout(volT);volT=setTimeout(function(){show(q("volume-overlay"),false)},1500)}
+function bump(d){vol=Math.max(0,Math.min(100,vol+d));q("volume-level").textContent=vol;q("volume-bar").firstChild.style.width=vol+"%";show(q("volume-overlay"),true);clearTimeout(volT);volT=setTimeout(function(){show(q("volume-overlay"),false)},1500)}
 q("volume-up-button").addEventListener("click",function(){bump(10)});q("volume-down-button").addEventListener("click",function(){bump(-10)});
 q("off-screen").addEventListener("click",powerOn);q("off-screen").addEventListener("keydown",function(e){if(e.key==="Enter"||e.key===" "){e.preventDefault();powerOn()}});
 r.addEventListener("keydown",function(e){if(e.key==="Escape")closeMenu()});
 document.addEventListener("pointerdown",function(e){if(shown("power-menu")&&!q("power-menu").contains(e.target)&&e.target!==pw)closeMenu()});
 q("power-menu").addEventListener("click",function(e){var a=e.target.getAttribute&&e.target.getAttribute("data-act");if(!a)return;show(q("power-menu"),false);
 if(a==="cancel"){pw.focus();return}
+if(a==="navstyle")return;
 if(a==="restart"){show(q("boot-screen"),true);var f=document.getElementById(${JSON.stringify(iframeId)});if(f&&f.contentWindow)f.contentWindow.location.reload();clearTimeout(bootT);bootT=setTimeout(function(){show(q("boot-screen"),false)},1200)}
 else{show(q("lock-screen"),false);show(q("off-screen"),true);pw.focus()}})})();
+${shadeClientScript(iframeId, skin)}
+${settingsClientScript(iframeId)}
+${appsClientScript(iframeId, phone)}
+${updateClientScript()}
+${lumiClientScript()}
+${guideClientScript()}
+(function nav(){var r=root();if(!r)return;var q=function(p){return r.querySelector('[data-part="'+p+'"]')};
+if(!q("home-screen")||!q("recents"))return;
+var classifySwipe=${classifySwipe.toString()},setVisibilityInPage=${setVisibilityInPage.toString()};
+var where="app",style="gesture",skin=${JSON.stringify(skin)};
+function show(el,on){if(el)el.hidden=!on}
+function appWin(){var f=document.getElementById(${JSON.stringify(iframeId)});return f&&f.contentWindow}
+function fire(state){var w=appWin();if(!w)return;try{w.eval("("+setVisibilityInPage.toString()+")("+JSON.stringify(state)+")")}catch(x){}}
+function go(next){var was=where;where=next;show(q("home-screen"),next==="home");show(q("recents"),next==="recents");r.setAttribute("data-where",next);
+if(was==="app"&&next!=="app")fire("background");if(was!=="app"&&next==="app")fire("active");
+if(was!==next){try{window.parent.postMessage({type:"pn:nav-state",where:next},"*")}catch(x){}}}
+window.addEventListener("message",function(e){var d=e.data;if(d&&d.type==="pn:nav"&&(d.where==="app"||d.where==="home"||d.where==="recents"))go(d.where)});
+var af=document.getElementById(${JSON.stringify(iframeId)});if(af)af.addEventListener("load",function(){if(where!=="app")fire("background")});
+function home(){go("home")}function recents(){go("recents")}
+function back(){if(where!=="app")return go("app");var w=appWin();if(!w)return;var b=w.document.querySelector('[aria-label="Back"],[role=button][aria-label="Back"]');if(b)b.click()}
+function kill(){var w=appWin();go("home");if(w)w.location.reload()}
+function setStyle(st){style=st;r.setAttribute("data-nav",st);show(q("nav-buttons"),st==="buttons");var t=q("nav-style-toggle");if(t)t.textContent=st==="buttons"?"Gesture navigation":"3-button navigation"}
+q("app-icon").addEventListener("click",function(){go("app")});
+q("recents-open").addEventListener("click",function(){go("app")});
+q("recents-close").addEventListener("click",kill);
+var cd=q("recents-card"),cy=null;cd.addEventListener("pointerdown",function(e){cy=e.clientY});cd.addEventListener("pointerup",function(e){if(cy!=null&&cy-e.clientY>80)kill();cy=null});
+if(q("nav-back")){q("nav-back").addEventListener("click",back);q("nav-home").addEventListener("click",home);q("nav-recents").addEventListener("click",recents)}
+var tg=q("nav-style-toggle");if(tg)tg.addEventListener("click",function(){setStyle(style==="buttons"?"gesture":"buttons")});
+function swipe(el,edge){var x0=null,y0,t0;
+el.addEventListener("pointerdown",function(e){if(e.target.closest&&e.target.closest("button"))return;x0=e.clientX;y0=e.clientY;t0=Date.now();try{el.setPointerCapture(e.pointerId)}catch(x){}});
+el.addEventListener("pointercancel",function(){x0=null});
+el.addEventListener("pointerup",function(e){if(x0==null)return;var a=classifySwipe({skin:skin,fromEdge:edge,dx:e.clientX-x0,dy:e.clientY-y0,ms:Date.now()-t0});x0=null;
+if(a==="home")home();else if(a==="recents")recents();else if(a==="back")back()})}
+swipe(q("edge-swipe"),"left");
+var bar=r.querySelector(".sf-bar");if(bar&&!(skin==="android"&&style==="buttons"))swipe(bar,"bottom");
+document.addEventListener("keydown",function(e){if(e.key==="Escape"&&where!=="app")go("app")});
+})();
 (function tick(){draw();var n=new Date();setTimeout(tick,(60-n.getSeconds())*1000-n.getMilliseconds()+50)})();
 // The app can change its top colour (a theme switch) without any event we can hear, so look again every 2 seconds. Skipped while the page is hidden.
 setInterval(function(){if(document.hidden)return;var f=document.getElementById(${JSON.stringify(iframeId)});if(f&&f.contentWindow)theme(f.contentWindow)},2000);
@@ -141,9 +186,11 @@ function battery(b) {
  * - dark: true gives light status text on a dark bar, false gives dark text on a light bar.
  * - status: { time, signal 0-4, wifi, airplane, battery (0-100, or { level, charging }) }.
  * - screen: optional HTML placed in the screen area (the page puts its iframe there).
+ * - lumi: draw Lumi beside the cutout (outside the app's screen). Default: on, but off in CI; SHIPVO_LUMI=off hides it anywhere.
+ * - guide: also draw Lumi's first-run guide (3 short steps, skippable, shown once per browser). Needs lumi. Default: off.
  * Returns { skin, width, height, outerWidth, outerHeight, html, css }. width and height are the screen size.
  */
-export function renderFrame({ skin = "android", dark = false, status, screen = "" } = {}) {
+export function renderFrame({ skin = "android", dark = false, status, screen = "", lumi = lumiDefault(), guide = false } = {}) {
   const k = SKINS[skin];
   if (!k) throw new Error(`Unknown skin "${skin}". Use "android" or "ios".`);
   const st = normalizeStatus(status);
@@ -152,11 +199,11 @@ export function renderFrame({ skin = "android", dark = false, status, screen = "
     ? `<span class="sf-cut sf-island" data-part="dynamic-island"></span>`
     : `<span class="sf-cut sf-hole" data-part="punch-hole"></span>`;
   const html = `<div class="sf-body" data-skin="${skin}" data-theme="${dark ? "dark" : "light"}" data-part="phone-body">`
-    + `<div class="sf-screen"><div class="sf-status" data-part="status-bar"><span class="sf-time" data-part="time">${st.time}</span>${shape}<span class="sf-icons">${icons(st)}</span></div>`
-    + `<div class="sf-content">${screen}</div>`
-    + lockScreenHtml(st.time) + bootScreenHtml() + offScreenHtml()
-    + `<div class="sf-vol" data-part="volume-overlay" role="status" aria-live="polite" hidden><span data-part="volume-level">50</span></div><div class="sf-menu" data-part="power-menu" role="menu" aria-label="Power menu" hidden><button role="menuitem" data-act="restart">Restart</button><button role="menuitem" data-act="poweroff">Power off</button><button role="menuitem" data-act="cancel">Cancel</button></div>`
-    + `<div class="sf-bar" data-part="${k.bottom}"><i></i></div></div>`
+    + `<div class="sf-screen"><div class="sf-status" data-part="status-bar"><span class="sf-time" data-part="time">${st.time}</span>${shape}${lumi ? lumiHtml() : ""}<span class="sf-icons">${icons(st)}</span></div>`
+    + `<div class="sf-content">${screen}</div>` + (lumi ? lumiCaptionHtml() : "") + updateBannerHtml()
+    + shadeHtml(skin) + `<span class="sf-edge" data-part="edge-swipe"></span>` + homeScreenHtml().replace(/<\/div>$/, settingsIconHtml() + storeIconHtml() + "</div>") + settingsHtml() + storeScreenHtml() + recentsHtml() + lockScreenHtml(st.time) + bootScreenHtml() + offScreenHtml() + (lumi && guide ? guideHtml() : "")
+    + `<div class="sf-vol" data-part="volume-overlay" role="status" aria-live="polite" hidden><span data-part="volume-level">50</span><i class="sf-vbar" data-part="volume-bar"><b style="width:50%"></b></i></div><div class="sf-menu" data-part="power-menu" role="menu" aria-label="Power menu" hidden><button role="menuitem" data-act="restart">Restart</button><button role="menuitem" data-act="poweroff">Power off</button>${skin === "android" ? `<button role="menuitem" data-act="navstyle" data-part="nav-style-toggle">3-button navigation</button>` : ""}<button role="menuitem" data-act="cancel">Cancel</button></div>`
+    + `<div class="sf-bar" data-part="${k.bottom}"><i></i>${skin === "android" ? navButtonsHtml() : ""}</div></div>`
     + `<button class="sf-btn sf-power" data-part="power-button" aria-label="Power"></button><button class="sf-btn sf-volup" data-part="volume-up-button" aria-label="Volume up"></button><button class="sf-btn sf-voldown" data-part="volume-down-button" aria-label="Volume down"></button>`
     + `<span class="sf-label" data-part="simulated-label">Simulated</span></div>`;
   const css = [
@@ -176,8 +223,17 @@ export function renderFrame({ skin = "android", dark = false, status, screen = "
     `.sf-lock,.sf-boot,.sf-off,.sf-menu,.sf-vol{position:absolute;z-index:5}.sf-lock[hidden],.sf-boot[hidden],.sf-off[hidden],.sf-menu[hidden],.sf-vol[hidden]{display:none}.sf-off{inset:0;z-index:7;background:#000;cursor:pointer}`,
     `.sf-lock{inset:0;background:#10151c;color:#fff;display:flex;flex-direction:column;align-items:center;justify-content:center;gap:14px;font-family:system-ui,sans-serif}.sf-lock-time{font-size:64px;font-weight:300}.sf-lock-hint{font-size:14px;opacity:.7}.sf-lock button{margin-top:8px;padding:10px 28px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff;font:600 15px system-ui,sans-serif;cursor:pointer}`,
     `.sf-boot{inset:0;z-index:6;background:#000;color:#fff;display:flex;align-items:center;justify-content:center;font:700 34px system-ui,sans-serif;letter-spacing:.04em}`,
-    `.sf-vol{top:80px;right:12px;padding:8px 14px;border-radius:14px;background:#222d;color:#fff;font:600 14px system-ui,sans-serif}`,
+    `.sf-vbar{display:block;width:90px;height:4px;margin-top:6px;border-radius:2px;background:#fff4}.sf-vbar b{display:block;height:100%;border-radius:2px;background:#fff}.sf-vol{top:80px;right:12px;padding:8px 14px;border-radius:14px;background:#222d;color:#fff;font:600 14px system-ui,sans-serif}`,
     `.sf-menu{left:50%;top:50%;transform:translate(-50%,-50%);display:flex;flex-direction:column;gap:8px;padding:14px;border-radius:16px;background:#222;box-shadow:0 8px 30px #0008}.sf-menu button{padding:10px 24px;border:0;border-radius:10px;background:#3a3d42;color:#fff;font:600 15px system-ui,sans-serif}`,
+    ...(lumi ? [lumiCss(k)] : []),
+    ...(lumi && guide ? [guideCss] : []),
+    shadeCss,
+    settingsCss,
+    storeCss,
+    updateCss,
+    `.sf-edge{position:absolute;left:0;top:${k.status}px;bottom:${k.bar}px;width:14px;z-index:3}.sf-home[hidden],.sf-recents[hidden],.sf-navbtns[hidden]{display:none}`,
+    navScreensCss(),
+    `.sf-bar{position:relative}.sf-navbtns{position:absolute;inset:0;display:flex;justify-content:space-around;align-items:center;background:var(--sf-bg)}.sf-navbtns button{border:0;background:none;color:var(--sf-fg);font-size:16px;padding:2px 24px;cursor:pointer}.sf-body[data-nav="buttons"] .sf-bar i{display:none}`,
     `.sf-label{position:absolute;left:0;right:0;bottom:3px;text-align:center;font:600 9px system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase;color:#9aa0a6}`,
   ].join("\n");
   return { skin, width: k.width, height: k.height, outerWidth, outerHeight, html, css };

package/guide.mjs

@@ -0,0 +1,44 @@
+// Lumi's first-run guide on the Shipvo Phone: three short steps (home screen, the Store, connecting an assistant).
+// It can be skipped, and once it is finished or skipped it never shows again on this browser. It sits in the phone frame
+// over the bottom of the screen, never in the app's own page, so the simulator's screenshots and screen tree do not see it.
+// It is drawn only when Lumi is drawn and the page asks for it (`guide: true`).
+
+export const GUIDE_KEY = "shipvo.lumi.guide";
+
+export const GUIDE_STEPS = [
+  { title: "Your home screen", text: "Go home to see your apps. Go home at any time to come back." },
+  { title: "The Store", text: "The Store icon on the home screen installs more apps on this phone." },
+  { title: "Connect an assistant", text: "To let an AI assistant drive this phone, run: claude mcp add shipvo -- npx -y @shipvo/mcp" },
+];
+
+/** Markup for the guide. Hidden until the page script finds that this browser has not seen it. */
+export function guideHtml() {
+  const steps = GUIDE_STEPS.map((s, i) => `<div class="sf-guide-step" data-step="${i + 1}"${i ? " hidden" : ""}><b>${s.title}</b><p>${s.text.replace(/&/g, "&amp;").replace(/</g, "&lt;")}</p></div>`).join("");
+  return `<div class="sf-guide" data-part="lumi-guide" role="dialog" aria-live="polite" aria-label="Welcome to Shipvo Phone" hidden>`
+    + `<span class="sf-guide-count" data-part="guide-count">1 of ${GUIDE_STEPS.length}</span>${steps}`
+    + `<div class="sf-guide-actions"><button type="button" data-part="guide-skip">Skip</button><button type="button" data-part="guide-next">Next</button></div></div>`;
+}
+
+export const guideCss = [
+  `.sf-guide{position:absolute;left:12px;right:12px;bottom:40px;z-index:4;box-sizing:border-box;padding:12px 14px;border-radius:16px;background:#10151c;color:#fff;border:1px solid #7fd6f5aa;box-shadow:0 0 14px #7fd6f555,0 6px 20px #0008;font:14px/1.4 system-ui,sans-serif}`,
+  `.sf-guide[hidden],.sf-guide [hidden]{display:none}`,
+  `.sf-guide p{margin:4px 0 0;overflow-wrap:anywhere}.sf-guide-count{float:right;font-size:11px;opacity:.7}`,
+  `.sf-guide-actions{display:flex;justify-content:flex-end;gap:8px;margin-top:10px}`,
+  `.sf-guide button{padding:6px 16px;border:1px solid #fff6;border-radius:999px;background:transparent;color:#fff;font:600 13px system-ui,sans-serif;cursor:pointer}`,
+  `.sf-guide [data-part=guide-next]{background:#7fd6f5;border-color:#7fd6f5;color:#10151c}.sf-guide button:focus-visible{outline:3px solid #4da3ff;outline-offset:2px}`,
+].join("\n");
+
+/** Browser script. Shows the guide on first launch, steps through it, and remembers a finish or a skip in localStorage. */
+export function guideClientScript() {
+  return `(function(){var K=${JSON.stringify(GUIDE_KEY)},g=document.querySelector('[data-part="lumi-guide"]');if(!g)return;
+function seen(){try{return localStorage.getItem(K)==="done"}catch(x){return false}}
+function save(){try{localStorage.setItem(K,"done")}catch(x){}}
+var s=g.querySelectorAll(".sf-guide-step"),i=0,c=g.querySelector('[data-part="guide-count"]'),n=g.querySelector('[data-part="guide-next"]');
+function lumi(st){if(window.shipvoLumi)window.shipvoLumi.set(st)}
+function draw(){for(var j=0;j<s.length;j++)s[j].hidden=j!==i;c.textContent=(i+1)+" of "+s.length;n.textContent=i===s.length-1?"Done":"Next"}
+function close(happy){save();g.hidden=true;lumi(happy?"happy":"idle")}
+g.querySelector('[data-part="guide-skip"]').addEventListener("click",function(){close(false)});
+n.addEventListener("click",function(){if(i>=s.length-1)return close(true);i++;draw()});
+document.addEventListener("keydown",function(e){if(e.key==="Escape"&&!g.hidden)close(false)});
+if(seen())return;draw();g.hidden=false})();`;
+}

package/lumi.mjs

@@ -0,0 +1,97 @@
+// Lumi, the glowing orb, drawn in the phone frame beside the camera cutout. Our own artwork.
+// Lumi lives in the frame's status bar, never in the app's screen: it is not inside `.sf-content`, it is hidden from
+// assistive tech and the labelled screen tree, and it takes no pointer input. The simulator's own page (screens, screenshots,
+// recordings for agents) never draws it, so agents and tests see the same app with Lumi on or off.
+
+export const LUMI_STATES = ["idle", "working", "happy", "worried"];
+
+/** True when Lumi is drawn by default. SHIPVO_LUMI=off|0|false|no hides it anywhere; on|1|true|yes shows it. With no setting it is off in CI and on otherwise. */
+export function lumiDefault(env = typeof process !== "undefined" ? process.env : {}) {
+  const v = String(env.SHIPVO_LUMI ?? "").trim().toLowerCase();
+  if (["off", "0", "false", "no"].includes(v)) return false;
+  if (["on", "1", "true", "yes"].includes(v)) return true;
+  const ci = String(env.CI ?? "").trim().toLowerCase();
+  return !(ci && ci !== "0" && ci !== "false");
+}
+
+const FACE = {
+  idle: `<path d="M8.6 15.4q2.4 1.6 4.8 0" fill="none" stroke="#10151c" stroke-width="1.3" stroke-linecap="round"/>`,
+  working: `<ellipse cx="11" cy="15.6" rx="1.3" ry="1.1" fill="#10151c"/>`,
+  happy: `<path d="M8 14.6q3 3.6 6 0z" fill="#10151c"/>`,
+  worried: `<path d="M8.8 16.6q2.2-1.8 4.4 0" fill="none" stroke="#10151c" stroke-width="1.3" stroke-linecap="round"/><path d="M6.6 8.2l3 .8M15.4 8.2l-3 .8" stroke="#10151c" stroke-width="1" stroke-linecap="round"/>`,
+};
+
+/**
+ * What Lumi shows for a result. `event` is { kind, error?, name?, detail? }:
+ * check-passed and flow-done give happy; page-error, crash, action-failed and check-failed give worried.
+ * The reason is one line taken from the real error or result (first line, spaces collapsed, at most 90 characters).
+ * Anything else, or an unusable event, returns null and Lumi stays as it is. Pure and self-contained, so the page can run it.
+ */
+export function lumiReaction(event) {
+  if (!event || typeof event !== "object") return null;
+  const one = (v) => {
+    const t = String(v && v.message ? v.message : v == null ? "" : v).split(/\r?\n/).map((x) => x.replace(/\s+/g, " ").trim()).find(Boolean) || "";
+    return t.length > 90 ? t.slice(0, 89) + "…" : t;
+  };
+  const name = one(event.name), err = one(event.error), detail = one(event.detail);
+  const why = (fallback) => err || detail || fallback;
+  switch (event.kind) {
+    case "check-passed": return { state: "happy", reason: name ? "Check passed: " + name : "Check passed" };
+    case "flow-done": return { state: "happy", reason: name ? "Flow finished: " + name : "Flow finished" };
+    case "page-error": return { state: "worried", reason: "Page error: " + why("the page threw an error") };
+    case "crash": return { state: "worried", reason: "Crash: " + why("the app stopped") };
+    case "action-failed": return { state: "worried", reason: (name ? "Action failed (" + name + "): " : "Action failed: ") + why("no reason given") };
+    case "check-failed": return { state: "worried", reason: (name ? "Check failed (" + name + "): " : "Check failed: ") + why("no reason given") };
+    default: return null;
+  }
+}
+
+/** Markup for Lumi. `state` is one of idle, working, happy, worried. */
+export function lumiHtml(state = "idle") {
+  const st = LUMI_STATES.includes(state) ? state : "idle";
+  const faces = LUMI_STATES.map((s) => `<g data-face="${s}"${s === st ? "" : " hidden"}>${FACE[s]}</g>`).join("");
+  return `<span class="sf-lumi" data-part="lumi" data-state="${st}" aria-hidden="true" inert>`
+    + `<svg viewBox="0 0 22 22" width="22" height="22" focusable="false"><defs><radialGradient id="sf-lumi-g" cx="40%" cy="35%" r="70%"><stop offset="0" stop-color="#e9fbff"/><stop offset=".6" stop-color="#7fd6f5"/><stop offset="1" stop-color="#3b9ad9"/></radialGradient></defs>`
+    + `<circle cx="11" cy="11" r="10" fill="url(#sf-lumi-g)"/>`
+    + `<g class="sf-lumi-eyes"><ellipse cx="7.8" cy="11" rx="1.4" ry="1.9" fill="#10151c"/><ellipse cx="14.2" cy="11" rx="1.4" ry="1.9" fill="#10151c"/></g>${faces}</svg></span>`;
+}
+
+/** The caption pill Lumi shows for the agent's current step. Hidden until a step is shown. Outside the app's screen tree like Lumi. */
+export const lumiCaptionHtml = () => `<span class="sf-lumi-cap" data-part="lumi-caption" aria-hidden="true" inert hidden></span>`;
+
+/** Style for Lumi. `top` and `offset` place it beside the cutout. Motion stops for people who ask for less of it. */
+export const lumiCss = (k) => [
+  // The glow must never paint over the app's screen below the status bar.
+  `.sf-status{overflow:hidden}`,
+  `.sf-lumi{position:absolute;left:50%;top:${Math.round((k.status - 22) / 2)}px;margin-left:${k.part === "dynamic-island" ? 66 : 20}px;width:22px;height:22px;pointer-events:none;z-index:3;animation:sf-lumi-float 3.6s ease-in-out infinite}`,
+  `.sf-lumi svg{display:block;border-radius:50%;box-shadow:0 0 6px 1px #7fd6f5aa;animation:sf-lumi-glow 2.8s ease-in-out infinite}`,
+  `.sf-lumi-eyes{transform-box:fill-box;transform-origin:center;animation:sf-lumi-blink 4.5s infinite}`,
+  `.sf-lumi [hidden]{display:none}`,
+  `.sf-lumi[data-state=working] svg{animation-duration:1.1s}.sf-lumi[data-state=working]{animation-duration:1.6s}`,
+  `.sf-lumi[data-state=happy] svg{box-shadow:0 0 9px 3px #ffe08aaa}.sf-lumi[data-state=worried] svg{box-shadow:0 0 7px 2px #ff9a8aaa}`,
+  `.sf-lumi-cap{position:absolute;left:50%;top:${k.status + 6}px;transform:translateX(-50%);max-width:80%;box-sizing:border-box;padding:4px 12px;border-radius:14px;background:#10151ce6;color:#fff;font:600 12px system-ui,sans-serif;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;pointer-events:none;z-index:4}.sf-lumi-cap[hidden]{display:none}`,
+  `@keyframes sf-lumi-float{0%,100%{transform:translateY(0)}50%{transform:translateY(-2px)}}`,
+  `@keyframes sf-lumi-glow{0%,100%{opacity:.88}50%{opacity:1;filter:brightness(1.12)}}`,
+  `@keyframes sf-lumi-blink{0%,92%,100%{transform:scaleY(1)}95%{transform:scaleY(.1)}}`,
+  `@media (prefers-reduced-motion:reduce){.sf-lumi,.sf-lumi svg,.sf-lumi-eyes{animation:none}}`,
+].join("\n");
+
+/**
+ * Browser script. `window.shipvoLumi.set(state, reason?)` changes Lumi's state; `react(event)` picks the state and reason from a result (see lumiReaction).
+ * A `{ type: "pn:lumi", state, reason? }` or `{ type: "pn:lumi", event }` message does the same. The reason sits in Lumi's `data-reason` and `title`
+ * and is cleared when the state has no reason.
+ * `window.shipvoLumi.say(text, state, holdMs)` (or `{ type: "pn:lumi", state, caption, hold }`) also shows a short caption.
+ * With `holdMs` > 0 the caption goes away and Lumi goes back to idle after that long. Touches only Lumi and its caption.
+ */
+export function lumiClientScript() {
+  return `(function(){var S=${JSON.stringify(LUMI_STATES)},T=0;var lumiReaction=${lumiReaction.toString()};
+function set(state,reason){if(S.indexOf(state)<0)return false;var l=document.querySelector('[data-part="lumi"]');if(!l)return false;l.setAttribute("data-state",state);
+if(typeof reason==="string"&&reason){l.setAttribute("data-reason",reason);l.setAttribute("title",reason)}else{l.removeAttribute("data-reason");l.removeAttribute("title")}
+var g=l.querySelectorAll("[data-face]");for(var i=0;i<g.length;i++)g[i].hidden=g[i].getAttribute("data-face")!==state;return true}
+function react(ev){var r=lumiReaction(ev);if(!r)return null;return set(r.state,r.reason)?r:null}
+function say(text,state,hold){clearTimeout(T);var c=document.querySelector('[data-part="lumi-caption"]');var ok=set(state||"working");
+if(c){var t=String(text==null?"":text).replace(/\\s+/g," ").trim().slice(0,80);c.textContent=t;c.hidden=!t}
+if(hold>0)T=setTimeout(function(){if(c){c.hidden=true;c.textContent=""}set("idle")},hold);return ok}
+if(typeof window==="undefined")return;window.shipvoLumi={set:set,react:react,say:say,states:S};
+window.addEventListener("message",function(e){var d=e.data;if(!d||d.type!=="pn:lumi")return;if(d.event)react(d.event);else if(typeof d.caption==="string")say(d.caption,d.state,Number(d.hold)||0);else set(d.state,d.reason)})})();`;
+}