@livx.cc/appwrap 0.61.19 → 0.61.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/appwrap",
-  "version": "0.61.19",
+  "version": "0.61.20",
   "description": "Wrap any PWA into a native app with native capabilities (appwrap runtime + @livx.cc/native-kit).",
   "license": "MIT",
   "author": "Elya Livshitz",

package/runtime/app/shell/config.ts

@@ -84,7 +84,7 @@ export const SHELL_CONFIG = {
    * present AND not `enabled:false`); when false the menu action, banner, and boot override are all
    * inert. `envs` = declared presets; `allowPattern` = anchored regex gating "Other" (default-deny
    * when ''). Stamped by `appwrap init`/`sync` — see `stampShellConfig`. */
-  envSwitcher: { enabled: false, envs: [] as { label: string; url: string }[], allowPattern: '' },
+  envSwitcher: { enabled: false, envs: [] as { label: string; url: string }[], allowPattern: '', params: [] as { key: string; label: string; options: string[]; optionsUrl: string; optionsPath: string; defaultValue?: string }[] },
   /** TCC-gated web APIs this build DECLARED (active modules + the config's `permissions{}`) — what the
    * document-start capability guard exposes to the page. NOT the same question as "is the Info.plist
    * usage string present": the plist also carries the webview baseline (NSCameraUsageDescription is

package/runtime/app/shell/env-switcher.ts

@@ -5,6 +5,7 @@ import { OVERRIDE_KEY, effectiveServerUrl, isUrlAllowed } from './server-url';
 import { bridge } from './bridge';
 import { refreshEnvBanner } from './env-banner';
 import { refreshEnvKeepAwake } from './env-keepawake';
+import { paramMenuLabel, showParamPicker, urlParamDefs } from './url-params';
 
 /**
  * Runtime env-switcher — re-point a `loader:'server'` shell between declared environments (prod / lab /
@@ -164,6 +165,8 @@ export async function showEnvSwitcher(): Promise<void> {
     const allowOther = !!SHELL_CONFIG.envSwitcher?.allowPattern;
     const actions = envs.map((e) => (e.url === active ? `${e.label} ✓` : e.label));
     if (allowOther) actions.push('Other…');
+    const params = urlParamDefs().map((p) => ({ p, label: paramMenuLabel(p) }));
+    actions.push(...params.map((x) => x.label));
     actions.push('Reset to default');
 
     const choice = await Dialogs.action({
@@ -176,6 +179,8 @@ export async function showEnvSwitcher(): Promise<void> {
 
     if (choice === 'Reset to default') return void (await applySwitch(null, 'default'));
     if (choice === 'Other…') return void (await promptOther());
+    const param = params.find((x) => x.label === choice);
+    if (param) return void (await showParamPicker(param.p, reloadToEffective));
 
     const label = choice.replace(/ ✓$/, '');
     const env = envs.find((e) => e.label === label);

package/runtime/app/shell/server-url.ts

@@ -58,6 +58,42 @@ export function isOverrideAllowed(url: string): boolean {
  * override against the same allowlist the switcher uses — the native menu isn't the only writer of the
  * key (any page JS can write it via `kit.storage.set`), so the read side must not trust it blindly. */
 export function effectiveServerUrl(): string {
+  return withUrlParams(effectiveBaseUrl());
+}
+
+/** Persisted values for the config-declared URL params (`envSwitcher.params`), `{ key: value }`. */
+export const URL_PARAMS_KEY = 'kit:urlParams';
+
+/** The persisted URL-param selections, filtered to keys DECLARED in `envSwitcher.params` (a page can write
+ * the key via `kit.storage`, so undeclared keys / non-string values are dropped). {} when disabled. */
+export function storedUrlParams(): Record<string, string> {
+  const declared = new Set((SHELL_CONFIG.envSwitcher?.params ?? []).map((p) => p.key));
+  if (SHELL_CONFIG.loader !== 'server' || !SHELL_CONFIG.envSwitcher?.enabled || !declared.size) return {};
+  try {
+    const raw = JSON.parse(ApplicationSettings.getString(URL_PARAMS_KEY, '') || '{}');
+    const out: Record<string, string> = {};
+    for (const [k, v] of Object.entries(raw ?? {})) if (declared.has(k) && typeof v === 'string' && v) out[k] = v;
+    return out;
+  } catch {
+    return {};
+  }
+}
+
+/** Apply the stored URL params to a load URL (a key already in the URL is REPLACED, not duplicated). */
+export function withUrlParams(url: string): string {
+  const params = Object.entries(storedUrlParams());
+  if (!params.length) return url;
+  try {
+    const u = new URL(url);
+    for (const [k, v] of params) u.searchParams.set(k, v);
+    return u.toString();
+  } catch {
+    return url; // unparseable base — load it untouched rather than corrupt it
+  }
+}
+
+/** The env base URL (override or build default) WITHOUT the URL params — what option sources resolve against. */
+export function effectiveBaseUrl(): string {
   if (SHELL_CONFIG.loader !== 'server') return SHELL_CONFIG.serverUrl;
   if (SHELL_CONFIG.envSwitcher?.enabled) {
     try {

package/runtime/app/shell/url-params.ts

@@ -0,0 +1,86 @@
+import { ApplicationSettings, Dialogs, Http } from '@nativescript/core';
+import { SHELL_CONFIG } from './config';
+import { URL_PARAMS_KEY, effectiveBaseUrl, storedUrlParams } from './server-url';
+
+/**
+ * Config-driven URL-param menu for the env-switcher (`envSwitcher.params`). Each declared param adds a
+ * "<Label>: <current>" entry to the Switch Environment sheet; picking a value persists it (`kit:urlParams`)
+ * and reloads the WebView with `?<key>=<value>` appended (see `withUrlParams` in server-url.ts). The first
+ * option, "default", means "no param" — or `?<key>=<defaultValue>` when the param declares one. Same gate as the env-switcher itself — no separate trust surface.
+ *
+ * Options come from a static `options` list and/or `optionsUrl` — a JSON GET resolved against the ACTIVE
+ * env's base URL (so a relative path follows an env switch). `optionsPath` (dot path) selects the value
+ * inside the response; an array yields its string items, an object yields its keys.
+ */
+
+export type UrlParamDef = (typeof SHELL_CONFIG.envSwitcher.params)[number];
+
+export const DEFAULT_OPTION = 'default';
+
+export function urlParamDefs(): UrlParamDef[] {
+  return SHELL_CONFIG.envSwitcher?.params ?? [];
+}
+
+/** Menu entry label for a param, e.g. "Segment: senior". */
+export function paramMenuLabel(p: UrlParamDef): string {
+  return `${p.label || p.key}: ${currentOption(p)}`;
+}
+
+/** The menu option currently selected — a stored `defaultValue` reads back as "default". */
+export function currentOption(p: UrlParamDef): string {
+  const v = storedUrlParams()[p.key];
+  return !v || v === p.defaultValue ? DEFAULT_OPTION : v;
+}
+
+/** Extract string options from a JSON response: walk `path`, then array → strings, object → keys. */
+export function extractOptions(json: unknown, path = ''): string[] {
+  let v: any = json;
+  for (const k of path.split('.').filter(Boolean)) v = v?.[k];
+  const list = Array.isArray(v) ? v : v && typeof v === 'object' ? Object.keys(v) : [];
+  return list.filter((s): s is string => typeof s === 'string' && !!s);
+}
+
+/** Resolve the param's options: "default" + static options + fetched options (deduped). A failed fetch
+ * is logged and falls back to the static list — the menu still opens. */
+export async function loadParamOptions(p: UrlParamDef): Promise<string[]> {
+  const opts = (p.options ?? []).filter((o) => o !== p.defaultValue);
+  if (p.optionsUrl) {
+    const url = new URL(p.optionsUrl, effectiveBaseUrl()).toString();
+    try {
+      const res = await Http.request({ url, method: 'GET', timeout: 8000 });
+      if (res.statusCode < 200 || res.statusCode >= 300) throw new Error(`HTTP ${res.statusCode}`);
+      opts.push(...extractOptions(res.content?.toJSON(), p.optionsPath));
+    } catch (e: any) {
+      console.warn(`AppWrap: url-param "${p.key}" options fetch failed (${url}): ${e?.message ?? e}`);
+    }
+  }
+  return [...new Set([DEFAULT_OPTION, ...opts])];
+}
+
+/** Persist one param pick. "default" (or '') stores the param's `defaultValue` when declared — an explicit
+ * reset sent to the page (e.g. `?segment=default`) — else clears it so the param is omitted. Only an
+ * explicit pick is ever sent; an untouched app never gets the defaultValue appended. */
+export function setUrlParam(p: UrlParamDef, value: string): void {
+  const next = { ...storedUrlParams() };
+  const v = !value || value === DEFAULT_OPTION ? p.defaultValue ?? '' : value;
+  if (v) next[p.key] = v;
+  else delete next[p.key];
+  ApplicationSettings.setString(URL_PARAMS_KEY, JSON.stringify(next));
+}
+
+/** Action sheet for one param; on a changed pick, persist + `reload()`. */
+export async function showParamPicker(p: UrlParamDef, reload: () => void): Promise<void> {
+  const current = currentOption(p);
+  const options = await loadParamOptions(p);
+  const choice = await Dialogs.action({
+    title: p.label || p.key,
+    message: `Current: ${current}`,
+    cancelButtonText: 'Cancel',
+    actions: options.map((o) => (o === current ? `${o} ✓` : o)),
+  });
+  if (!choice || choice === 'Cancel') return;
+  const value = choice.replace(/ ✓$/, '');
+  if (value === current) return;
+  setUrlParam(p, value);
+  reload();
+}

package/src/cli.ts

@@ -975,6 +975,11 @@ export function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
     enabled: !!es && es.enabled !== false,
     envs: (es?.envs ?? []).map((e) => ({ label: String(e.label), url: String(e.url) })),
     allowPattern: es?.allowPattern ?? '',
+    params: (es?.params ?? []).map((p) => ({
+      key: String(p.key), label: String(p.label ?? p.key), options: (p.options ?? []).map(String),
+      optionsUrl: String(p.optionsUrl ?? ''), optionsPath: String(p.optionsPath ?? ''),
+      ...(p.defaultValue ? { defaultValue: String(p.defaultValue) } : {}),
+    })),
   };
   const hold = cfg.splashHold;
   const splash = {
@@ -1012,7 +1017,7 @@ export const SHELL_CONFIG = {
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
   iosHideKeyboardAccessory: ${JSON.stringify(cfg.iosHideKeyboardAccessory ?? false)},
   splash: ${JSON.stringify(splash)} as { hold: boolean; timeoutMs: number; logo: boolean },
-  envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
+  envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string; params: { key: string; label: string; options: string[]; optionsUrl: string; optionsPath: string; defaultValue?: string }[] },
   webCaps: ${JSON.stringify(webCaps)} as { camera: boolean; microphone: boolean; geolocation: boolean },
 };
 `;

package/src/config.ts

@@ -38,6 +38,23 @@ export interface EnvSwitcherConfig {
   allowPattern?: string;
   /** Deeplink auto-switch (Phase 2 — not yet implemented). Opt-in. */
   deeplink?: boolean;
+  /** Extra URL query params pickable from the switch menu (same gate). Each adds "<label>: <value>";
+   * a pick persists and reloads with `?<key>=<value>` ("default" = param omitted). */
+  params?: EnvSwitcherParam[];
+}
+
+/** One switchable URL param. Options = static `options` + `optionsUrl` (JSON GET, resolved against the
+ * ACTIVE env's URL, so a relative path follows env switches); `optionsPath` dot-path picks the value —
+ * an array gives its strings, an object gives its keys. */
+export interface EnvSwitcherParam {
+  key: string;
+  label?: string;
+  options?: string[];
+  optionsUrl?: string;
+  optionsPath?: string;
+  /** Value sent when "default" is picked (e.g. 'default' → `?segment=default`, an explicit reset). Absent →
+   * the param is omitted. Only sent after an explicit pick, never on an untouched app. */
+  defaultValue?: string;
 }
 
 /** iOS share-extension direct sync (`shareTarget.directSync`). When configured, the generated