@colixsystems/widget-sdk 0.199.0 → 0.201.0

package/README.md

@@ -83,7 +83,62 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.199.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.201.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.201.0 (contract 1.160.0)
+
+**A page badge can stay live while its page is closed — `manifest.badgeCounter` + `useBadgeCount(props)`.** `usePageBadge` only runs while your widget is on screen, so a chat's unread count used to reach the menu only after someone opened the chat's page. Declare `badgeCounter: true` and export a counting hook from every platform entry, and the app runs it in the background for each placement on a page its menu links to (installed marketplace widgets, your workspace's own included):
+
+```jsx
+import { useMemo } from "react";
+import {
+  useDatastoreQuery,
+  useDatastoreSubscription,
+  usePageBadge,
+  useStableQuery,
+  useUser,
+} from "@colixsystems/widget-sdk";
+
+function useOpenTasks({ tasksTableId }) {
+  const me = useUser().id;
+  const table = me ? tasksTableId : null;
+  const { data, loading, refetch } = useDatastoreQuery(
+    table,
+    useStableQuery(() => ({ filter: { Assignee: "eq:me", Done: "eq:false" }, limit: 500 })),
+  );
+  // Stay live while the page is closed: re-read whenever a task changes.
+  const handlers = useMemo(
+    () => ({ onCreated: refetch, onUpdated: refetch, onDeleted: refetch }),
+    [refetch],
+  );
+  useDatastoreSubscription(table, handlers);
+  return loading ? null : data.length;
+}
+
+// The host runs this while the page is closed.
+export function useBadgeCount(props) {
+  return useOpenTasks(props);
+}
+
+export default function TaskList(props) {
+  usePageBadge(useOpenTasks(props));
+  // ...
+}
+```
+
+- **The hook** is called with the placement's resolved props, inside the widget's own context. Return a whole number, or `null` while the count is not known yet. It must only read: no rendering, no data writes, no navigation, no events or toasts, nothing marked read, and no `usePageBadge`, `useScreenTitle`, `useSectionEmpty` or `useWidgetRoute` setter.
+- **The host enforces read-only.** A counter's datastore and directory offer only their read methods and realtime subscriptions, and notification mutes only `get`/`list`. Writes, typing signals, payments, `notifications.send`, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable, exactly as on a host that does not provide them.
+- **Stay live.** The counter runs for as long as the app is open, so subscribe to changes (as above) or refetch on a slow interval; a counter that reads once goes stale.
+- **Share one implementation.** Count with the same function the widget badges with, so the background count and the open widget never disagree.
+- **`usePageBadge(null)` is a new signal.** An explicit `null` means "not known yet": nothing is written and the current badge stays. Pass `null` until your first load settles, so opening the page never flashes the badge to 0. `undefined`, `0` and any other value that is not a positive number still clear this widget's share, exactly as before, so `usePageBadge(data?.count)` behaves as it always has.
+- **New linter rules.** `badge-counter-export-missing` (error) refuses a widget that declares `badgeCounter` while an entry has no `useBadgeCount` export; `badge-counter-undeclared` (warning) flags the export without the declaration. The export name is published as `CONTRACT.badgeCounterExport`.
+- **Types:** `WidgetManifest.badgeCounter` and `BadgeCounterHook`.
+
+Additive: a widget without `badgeCounter` is unaffected.
+
+### What's new in 0.200.0 (contract 1.159.0)
+
+**Host sign-in screen: a logo on the card.** `resolveLoginLogoUrl(login, appLogoUrl)` answers which logo the built-in sign-in card shows: the author's own sign-in logo (`login.logoUrlResolved`, the host's resolution of `login.logoAssetId`, else the pasted `login.logoUrl`), else the app logo the host already resolved, else `null` for the stock mark. Every candidate passes the same scheme allowlist as the sign-in background, so a `javascript:` or `data:` value never reaches either host. It is kept apart from `normaliseLoginDesign` because an app logo alone is not an authored design. Widgets are unaffected: this is the host surface (`@colixsystems/widget-sdk/host`), and the widget contract version does not change.
 
 ### What's new in 0.199.0 (contract 1.159.0)
 

package/dist/contract.cjs

@@ -1065,7 +1065,10 @@ const HOOKS = [
     description:
       "Puts count on the menu entry or tab of the page this widget is on (a chat's unread messages, open tasks). " +
       "The host sums every widget on the page and keeps the last count after the widget leaves the screen, until it " +
-      "reports again; 0, or anything not a positive number, clears this widget's share. Returns { supported }: false " +
+      "reports again; 0, undefined, or any other value that is not a positive number, clears this widget's share. " +
+      "An explicit null means the count is not known yet and keeps the current badge (pass null until the first load " +
+      "settles, so the badge never flashes to 0). manifest.badgeCounter keeps the badge live while the page is closed; " +
+      "see that field for who may declare it. Returns { supported }: false " +
       "on a host without page badges (the Builder canvas), where it does nothing. Call it at render with the current " +
       "count, never in a loop. Backed by ctx.navigation.setBadge. Identical on web (Player) and the Expo export.",
     returnShape: {
@@ -3047,6 +3050,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when the widget draws a strip of live figures (counts, totals, averages) about the records it shows, or is itself a strip of figures. The AppStudio app-builder reads this when it places an already-installed widget: it counts the widget as the page's figures, so it does not plan a second strip of figures beside it. Set it to match what the component actually renders; leave it false (or omit) when the widget draws no figures.",
     default: false,
   },
+  badgeCounter: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -5305,7 +5315,14 @@ const CONTRACT = deepFreeze({
   //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
   //    New `useBundledAsset(fileName)` resolves one through the new
   //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
-  version: "1.159.0",
+  // 1.160.0: additive (sc-10829) — optional manifest field `badgeCounter`:
+  //    the entry exports `useBadgeCount(props)` (name in `badgeCounterExport`)
+  //    and the host runs it while the widget's page is closed, so the page
+  //    badge stays live; the host gives a counter a read-only context.
+  //    `usePageBadge(null)` now means "not known yet" and keeps the current
+  //    badge; `undefined` still clears it. Linter rules `badge-counter-export-missing`
+  //    (error) and `badge-counter-undeclared` (warning).
+  version: "1.160.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5331,6 +5348,8 @@ const CONTRACT = deepFreeze({
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
+  // sc-10829 — the hook a `badgeCounter: true` entry exports by name.
+  badgeCounterExport: "useBadgeCount",
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,

package/dist/contract.js

@@ -1065,7 +1065,10 @@ const HOOKS = [
     description:
       "Puts count on the menu entry or tab of the page this widget is on (a chat's unread messages, open tasks). " +
       "The host sums every widget on the page and keeps the last count after the widget leaves the screen, until it " +
-      "reports again; 0, or anything not a positive number, clears this widget's share. Returns { supported }: false " +
+      "reports again; 0, undefined, or any other value that is not a positive number, clears this widget's share. " +
+      "An explicit null means the count is not known yet and keeps the current badge (pass null until the first load " +
+      "settles, so the badge never flashes to 0). manifest.badgeCounter keeps the badge live while the page is closed; " +
+      "see that field for who may declare it. Returns { supported }: false " +
       "on a host without page badges (the Builder canvas), where it does nothing. Call it at render with the current " +
       "count, never in a loop. Backed by ctx.navigation.setBadge. Identical on web (Player) and the Expo export.",
     returnShape: {
@@ -3043,6 +3046,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when the widget draws a strip of live figures (counts, totals, averages) about the records it shows, or is itself a strip of figures. The AppStudio app-builder reads this when it places an already-installed widget: it counts the widget as the page's figures, so it does not plan a second strip of figures beside it. Set it to match what the component actually renders; leave it false (or omit) when the widget draws no figures.",
     default: false,
   },
+  badgeCounter: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -5301,7 +5311,14 @@ const CONTRACT = deepFreeze({
   //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
   //    New `useBundledAsset(fileName)` resolves one through the new
   //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
-  version: "1.159.0",
+  // 1.160.0: additive (sc-10829) — optional manifest field `badgeCounter`:
+  //    the entry exports `useBadgeCount(props)` (name in `badgeCounterExport`)
+  //    and the host runs it while the widget's page is closed, so the page
+  //    badge stays live; the host gives a counter a read-only context.
+  //    `usePageBadge(null)` now means "not known yet" and keeps the current
+  //    badge; `undefined` still clears it. Linter rules `badge-counter-export-missing`
+  //    (error) and `badge-counter-undeclared` (warning).
+  version: "1.160.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5327,6 +5344,8 @@ const CONTRACT = deepFreeze({
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
+  // sc-10829 — the hook a `badgeCounter: true` entry exports by name.
+  badgeCounterExport: "useBadgeCount",
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,

package/dist/emoji-picker.js

@@ -10,5 +10,6 @@
 import * as ReactNative from "react-native-web";
 import { makeEmojiPicker } from "./emoji-picker-view.js";
 import { Overlay } from "./overlay.js";
+import { TextInput } from "./primitives.js";
 
-export const EmojiPicker = makeEmojiPicker({ ...ReactNative, Overlay });
+export const EmojiPicker = makeEmojiPicker({ ...ReactNative, TextInput, Overlay });

package/dist/hooks.js

@@ -621,8 +621,10 @@ export function useFilePreview(file) {
   return { uri };
 }
 
-// A count the host can draw: a whole number, 0 for nothing to show.
+// A count the host can draw: a whole number, 0 for nothing to show, null
+// only when the widget explicitly says it does not know yet.
 function _badgeCount(count) {
+  if (count === null) return null;
   return typeof count === "number" && Number.isFinite(count) && count > 0 ? Math.floor(count) : 0;
 }
 
@@ -631,8 +633,9 @@ function _badgeCount(count) {
  * on, such as a chat's unread messages. Returns `{ supported }`. The host sums
  * every widget on the page and keeps the last count after the widget leaves
  * the screen, until it reports again; 0 (or anything not a positive number)
- * clears this widget's share. A host without page badges (the Builder canvas)
- * ignores it.
+ * clears this widget's share. sc-10829: an explicit null means "not known
+ * yet" and keeps the current badge; undefined still clears. A host without
+ * page badges (the Builder canvas) ignores it.
  */
 export function usePageBadge(count) {
   const ctx = useWidgetContextOrThrow("usePageBadge");
@@ -640,7 +643,7 @@ export function usePageBadge(count) {
   const setBadge = typeof nav.setBadge === "function" ? nav.setBadge : null;
   const value = _badgeCount(count);
   useEffect(() => {
-    if (setBadge) setBadge(value);
+    if (setBadge && value !== null) setBadge(value);
   }, [setBadge, value]);
   return { supported: Boolean(setBadge) };
 }

package/dist/host.d.ts

@@ -460,6 +460,12 @@ export interface LoginDesign {
 /** The sign-in screen's authored design, or null when nothing is configured. */
 export function normaliseLoginDesign(raw: unknown): LoginDesign | null;
 
+/** sc-10845 — the sign-in card's logo: the author's own, else the app logo. */
+export function resolveLoginLogoUrl(
+  login: unknown,
+  appLogoUrl: string | null | undefined,
+): string | null;
+
 /** sc-7800 — true when a stored value is a `theme:<path>` colour binding. */
 export function isThemeTokenRef(value: unknown): boolean;
 

package/dist/host.js

@@ -128,6 +128,7 @@ export {
   LOGIN_TEXT_MAX_LENGTH,
   normaliseThemeGradient,
   normaliseLoginDesign,
+  resolveLoginLogoUrl,
 } from "./theme-background.js";
 
 // sc-8448: one DATETIME local-clock conversion for the picker and the Studio.

package/dist/index.d.ts

@@ -397,8 +397,23 @@ export interface WidgetManifest {
    * /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/, value ≤1 KB.
    */
   translations?: Record<string, { en: string } & Record<string, string>>;
+  /**
+   * Optional (sc-10829, default false). True when every platform entry also
+   * exports `useBadgeCount(props)` (a `BadgeCounterHook`), which the host runs
+   * while the widget's page is closed so its menu badge stays live.
+   */
+  badgeCounter?: boolean;
 }
 
+/**
+ * sc-10829 — the `useBadgeCount` export of a `badgeCounter: true` widget. Called
+ * with the instance's resolved props inside the widget's own context; returns
+ * the page badge count, or `null` while it is not known yet. It only reads (the
+ * host gives it read-only clients and no device, payment or AI access): no
+ * rendering, writes, navigation, events, toasts or page-chrome hooks.
+ */
+export type BadgeCounterHook = (props: Record<string, unknown>) => number | null;
+
 /** A React Native shadow style object — one level of `ThemeTokens.elevation`. */
 export interface ElevationLevel {
   shadowColor?: string;
@@ -1821,17 +1836,19 @@ export function useNavigation(): {
  */
 export function useRouteParams(): Record<string, unknown>;
 
-/**
- * sc-10268 — puts `count` on the menu entry or tab of the page this widget is
- * on. The host sums the page's widgets and keeps the last count after the
- * widget leaves the screen; 0 clears this widget's share.
- */
 /**
  * sc-10268 — `{ uri }` an `<Image>` can show for a picked file before it is
  * uploaded. Null for no file, or a host that cannot preview one.
  */
 export function useFilePreview(file: unknown): { uri: string | null };
 
+/**
+ * sc-10268 — puts `count` on the menu entry or tab of the page this widget is
+ * on. The host sums the page's widgets and keeps the last count after the
+ * widget leaves the screen; 0 or `undefined` clears this widget's share.
+ * sc-10829: an explicit `null` means the count is not known yet and keeps the
+ * current badge.
+ */
 export function usePageBadge(count: number | null | undefined): {
   supported: boolean;
 };
@@ -3851,6 +3868,8 @@ export interface AiWidgetContract {
     >
   >;
   readonly bundleExportContract: ReadonlyArray<ContractBundleShape>;
+  /** sc-10829 — the export name of a `badgeCounter: true` entry's hook. */
+  readonly badgeCounterExport: "useBadgeCount";
   readonly bannedApis: ReadonlyArray<ContractBannedApi>;
   readonly allowedBareImports: ReadonlyArray<string>;
   /** Bare specifiers the web host provides by exact name; a widget bundle never inlines them. */

package/dist/linter.cjs

@@ -1992,6 +1992,54 @@ function lintEditability(manifest, files) {
   return { ok: true, findings };
 }
 
+// sc-10829 — `manifest.badgeCounter` promises the host a hook it can run
+// while the page is closed; each shipped entry must export it by name.
+function _exportedNameLine(code, name) {
+  const declared = new RegExp(
+    `\\bexport\\s+(?:(?:async\\s+)?function\\b\\s*\\*?\\s*|(?:const|let|var)\\s+)${name}\\b`,
+  );
+  const hit = declared.exec(code);
+  if (hit) return code.slice(0, hit.index).split("\n").length;
+  for (const clause of code.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+    const names = clause[1].split(",").map((part) => part.trim().split(/\s+as\s+/).pop().trim());
+    if (names.includes(name)) return code.slice(0, clause.index).split("\n").length;
+  }
+  return 0;
+}
+
+function _badgeCounterRules(source, manifest) {
+  if (!manifest || typeof manifest !== "object") return [];
+  const name = CONTRACT.badgeCounterExport;
+  const line = _exportedNameLine(_stripNonCode(source), name);
+  if (manifest.badgeCounter === true && line === 0) {
+    return [
+      {
+        rule: "badge-counter-export-missing",
+        severity: "error",
+        label:
+          `manifest.badgeCounter is true but this entry does not export ${name}(props). ` +
+          "Export the hook from every platform entry, or drop badgeCounter.",
+        line: 0,
+        snippet: "",
+      },
+    ];
+  }
+  if (manifest.badgeCounter !== true && line > 0) {
+    return [
+      {
+        rule: "badge-counter-undeclared",
+        severity: "warning",
+        label:
+          `This entry exports ${name} but manifest.badgeCounter is not true, so the host never runs it. ` +
+          "Declare badgeCounter: true, or remove the export.",
+        line,
+        snippet: source.split(/\r?\n/)[line - 1].trim().slice(0, 200),
+      },
+    ];
+  }
+  return [];
+}
+
 function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -2070,6 +2118,7 @@ function lintSource(source, options) {
     })),
   );
   findings.push(..._manifestActionRules(options && options.manifest));
+  findings.push(..._badgeCounterRules(source, options && options.manifest));
   const hasErrors = findings.some((f) => f.severity !== "warning");
   return { ok: !hasErrors, findings };
 }

package/dist/linter.js

@@ -2055,6 +2055,54 @@ export function lintEditability(manifest, files) {
   return { ok: true, findings };
 }
 
+// sc-10829 — `manifest.badgeCounter` promises the host a hook it can run
+// while the page is closed; each shipped entry must export it by name.
+function _exportedNameLine(code, name) {
+  const declared = new RegExp(
+    `\\bexport\\s+(?:(?:async\\s+)?function\\b\\s*\\*?\\s*|(?:const|let|var)\\s+)${name}\\b`,
+  );
+  const hit = declared.exec(code);
+  if (hit) return code.slice(0, hit.index).split("\n").length;
+  for (const clause of code.matchAll(/\bexport\s*\{([^}]*)\}/g)) {
+    const names = clause[1].split(",").map((part) => part.trim().split(/\s+as\s+/).pop().trim());
+    if (names.includes(name)) return code.slice(0, clause.index).split("\n").length;
+  }
+  return 0;
+}
+
+function _badgeCounterRules(source, manifest) {
+  if (!manifest || typeof manifest !== "object") return [];
+  const name = CONTRACT.badgeCounterExport;
+  const line = _exportedNameLine(_stripNonCode(source), name);
+  if (manifest.badgeCounter === true && line === 0) {
+    return [
+      {
+        rule: "badge-counter-export-missing",
+        severity: "error",
+        label:
+          `manifest.badgeCounter is true but this entry does not export ${name}(props). ` +
+          "Export the hook from every platform entry, or drop badgeCounter.",
+        line: 0,
+        snippet: "",
+      },
+    ];
+  }
+  if (manifest.badgeCounter !== true && line > 0) {
+    return [
+      {
+        rule: "badge-counter-undeclared",
+        severity: "warning",
+        label:
+          `This entry exports ${name} but manifest.badgeCounter is not true, so the host never runs it. ` +
+          "Declare badgeCounter: true, or remove the export.",
+        line,
+        snippet: source.split(/\r?\n/)[line - 1].trim().slice(0, 200),
+      },
+    ];
+  }
+  return [];
+}
+
 export function lintSource(source, options) {
   if (typeof source !== "string") {
     return {
@@ -2142,6 +2190,7 @@ export function lintSource(source, options) {
   );
   // REQ-WIDGET-ACTION — structural validation of manifest-declared actions.
   findings.push(..._manifestActionRules(options && options.manifest));
+  findings.push(..._badgeCounterRules(source, options && options.manifest));
   const hasErrors = findings.some((f) => f.severity !== "warning");
   return { ok: !hasErrors, findings };
 }

package/dist/manifest.cjs

@@ -325,6 +325,12 @@ function validateManifest(m) {
     validateManifestTranslations(manifest.translations, manifest.id, errors);
   }
 
+  pushIf(
+    errors,
+    manifest.badgeCounter === undefined || typeof manifest.badgeCounter === "boolean",
+    "manifest.badgeCounter must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/manifest.js

@@ -371,6 +371,12 @@ function validateManifest(m) {
     validateManifestTranslations(manifest.translations, manifest.id, errors);
   }
 
+  pushIf(
+    errors,
+    manifest.badgeCounter === undefined || typeof manifest.badgeCounter === "boolean",
+    "manifest.badgeCounter must be a boolean when present",
+  );
+
   return errors.length === 0 ? { ok: true } : { ok: false, errors };
 }
 

package/dist/markdown-input.js

@@ -6,5 +6,10 @@ import * as ReactNative from "react-native-web";
 import { makeMarkdownInput } from "./markdown-input-view.js";
 import { RichText } from "./richtext.js";
 import { Overlay } from "./overlay.js";
+import { TextInput } from "./primitives.js";
 
-export const MarkdownInput = makeMarkdownInput(ReactNative, RichText, Overlay);
+export const MarkdownInput = makeMarkdownInput(
+  { ...ReactNative, TextInput },
+  RichText,
+  Overlay,
+);

package/dist/primitives.js

@@ -40,13 +40,14 @@
 // static re-export tracing. Behaviour is identical to the old
 // `react-native` alias path on the web.
 import * as ReactNative from "react-native-web";
+import { makeTextInput } from "./text-input-view.js";
 
 export const Text = ReactNative.Text;
 export const View = ReactNative.View;
 export const Pressable = ReactNative.Pressable;
 export const Image = ReactNative.Image;
 export const ScrollView = ReactNative.ScrollView;
-export const TextInput = ReactNative.TextInput;
+export const TextInput = makeTextInput(ReactNative.TextInput);
 // Additional cross-platform primitives the AI agent + handwritten
 // widgets commonly reach for. All work in both react-native-web and
 // native react-native without per-platform code.

package/dist/text-field.js

@@ -3,5 +3,6 @@
 
 import * as ReactNative from "react-native-web";
 import { makeTextField } from "./text-field-view.js";
+import { TextInput } from "./primitives.js";
 
-export const TextField = makeTextField(ReactNative);
+export const TextField = makeTextField({ ...ReactNative, TextInput });

package/dist/text-input-view.js

@@ -0,0 +1,27 @@
+// The web `<TextInput>`: the host's input with the touch font floor. Native
+// has no focus zoom, so ./primitives.native.js re-exports RN's input as is.
+
+import React from "react";
+import { withTouchInputFontFloor } from "./touch-input-font-floor.js";
+
+function hasCoarsePointer() {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(pointer: coarse)").matches
+  );
+}
+
+/**
+ * @param {any} BaseTextInput react-native-web's `TextInput`.
+ * @returns a `TextInput` taking the same props and ref.
+ */
+export function makeTextInput(BaseTextInput) {
+  return React.forwardRef(function TextInput({ style, ...rest }, ref) {
+    return React.createElement(BaseTextInput, {
+      ...rest,
+      ref,
+      style: withTouchInputFontFloor(style, hasCoarsePointer()),
+    });
+  });
+}

package/dist/theme-background.cjs

@@ -68,8 +68,8 @@ function normaliseImageUrl(raw) {
   if (typeof raw !== "string") return null;
   const url = raw.trim();
   if (!url) return null;
-  // A workspace upload is served same-origin as an absolute path.
-  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  // A same-origin path; `/\host` and whitespace are foreign hosts to a browser.
+  if (/^\/(?![/\\])\S*$/.test(url)) return url;
   return /^https?:\/\/\S+$/i.test(url) ? url : null;
 }
 
@@ -135,4 +135,27 @@ function normaliseLoginDesign(raw) {
   return configured ? design : null;
 }
 
-module.exports = { LOGIN_TEXT_MAX_LENGTH, normaliseThemeGradient, normaliseLoginDesign };
+/**
+ * sc-10845 — the sign-in card's logo: the author's own, else the app logo,
+ * else null. Hosts resolve `logoAssetId` into `logoUrlResolved` first. Not in
+ * `normaliseLoginDesign`: an app logo alone is not an authored design.
+ *
+ * @param {object|null|undefined} login - `themeConfig.login`.
+ * @param {string|null|undefined} appLogoUrl - the host's resolved app logo.
+ * @returns {string|null}
+ */
+function resolveLoginLogoUrl(login, appLogoUrl) {
+  const own =
+    login && typeof login === "object"
+      ? normaliseImageUrl(login.logoUrlResolved) ||
+        normaliseImageUrl(login.logoUrl)
+      : null;
+  return own || normaliseImageUrl(appLogoUrl);
+}
+
+module.exports = {
+  LOGIN_TEXT_MAX_LENGTH,
+  normaliseThemeGradient,
+  normaliseLoginDesign,
+  resolveLoginLogoUrl,
+};

package/dist/theme-background.js

@@ -60,8 +60,8 @@ function normaliseImageUrl(raw) {
   if (typeof raw !== "string") return null;
   const url = raw.trim();
   if (!url) return null;
-  // A workspace upload is served same-origin as an absolute path.
-  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  // A same-origin path; `/\host` and whitespace are foreign hosts to a browser.
+  if (/^\/(?![/\\])\S*$/.test(url)) return url;
   return /^https?:\/\/\S+$/i.test(url) ? url : null;
 }
 
@@ -126,3 +126,21 @@ export function normaliseLoginDesign(raw) {
   const configured = Object.values(design).some((value) => value !== null);
   return configured ? design : null;
 }
+
+/**
+ * sc-10845 — the sign-in card's logo: the author's own, else the app logo,
+ * else null. Hosts resolve `logoAssetId` into `logoUrlResolved` first. Not in
+ * `normaliseLoginDesign`: an app logo alone is not an authored design.
+ *
+ * @param {object|null|undefined} login - `themeConfig.login`.
+ * @param {string|null|undefined} appLogoUrl - the host's resolved app logo.
+ * @returns {string|null}
+ */
+export function resolveLoginLogoUrl(login, appLogoUrl) {
+  const own =
+    login && typeof login === "object"
+      ? normaliseImageUrl(login.logoUrlResolved) ||
+        normaliseImageUrl(login.logoUrl)
+      : null;
+  return own || normaliseImageUrl(appLogoUrl);
+}

package/dist/touch-input-font-floor.js

@@ -0,0 +1,22 @@
+// iOS Safari zooms the page when a focused field's text is under 16px, and
+// never zooms back out. Platform-free so it is testable without a DOM.
+
+import { flattenStyle } from "./flatten-style.js";
+
+export const MIN_TOUCH_INPUT_FONT_SIZE = 16;
+
+/**
+ * `style` with its font size raised to the touch floor. An unset size is
+ * floored too: react-native-web's own input default is 14px.
+ *
+ * @param {object|Array|null|undefined|false} style
+ * @param {boolean} isTouch whether the primary pointer is a finger
+ * @returns {object|Array|null|undefined|false} `style` itself when unchanged.
+ */
+export function withTouchInputFontFloor(style, isTouch) {
+  if (!isTouch) return style;
+  const { fontSize } = flattenStyle(style);
+  if (typeof fontSize === "string") return style;
+  if (fontSize >= MIN_TOUCH_INPUT_FONT_SIZE) return style;
+  return [style, { fontSize: MIN_TOUCH_INPUT_FONT_SIZE }];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.199.0",
+  "version": "0.201.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1065,7 +1065,10 @@ const HOOKS = [
     description:
       "Puts count on the menu entry or tab of the page this widget is on (a chat's unread messages, open tasks). " +
       "The host sums every widget on the page and keeps the last count after the widget leaves the screen, until it " +
-      "reports again; 0, or anything not a positive number, clears this widget's share. Returns { supported }: false " +
+      "reports again; 0, undefined, or any other value that is not a positive number, clears this widget's share. " +
+      "An explicit null means the count is not known yet and keeps the current badge (pass null until the first load " +
+      "settles, so the badge never flashes to 0). manifest.badgeCounter keeps the badge live while the page is closed; " +
+      "see that field for who may declare it. Returns { supported }: false " +
       "on a host without page badges (the Builder canvas), where it does nothing. Call it at render with the current " +
       "count, never in a loop. Backed by ctx.navigation.setBadge. Identical on web (Player) and the Expo export.",
     returnShape: {
@@ -3043,6 +3046,13 @@ const MANIFEST_SCHEMA = {
       "Optional (default false). TRUE when the widget draws a strip of live figures (counts, totals, averages) about the records it shows, or is itself a strip of figures. The AppStudio app-builder reads this when it places an already-installed widget: it counts the widget as the page's figures, so it does not plan a second strip of figures beside it. Set it to match what the component actually renders; leave it false (or omit) when the widget draws no figures.",
     default: false,
   },
+  badgeCounter: {
+    type: "boolean",
+    required: false,
+    description:
+      "Optional (default false). TRUE when every platform entry also exports useBadgeCount(props): a hook returning the count the widget puts on its page's menu entry with usePageBadge, so the app keeps that badge live while the page is closed. The host runs counters for installed marketplace widgets (the workspace's own published widgets included); the platform's built-in widgets declare none. It calls the hook with the instance's resolved props, inside the widget's own context; the hook returns a whole number, or null while the count is not known yet. It only reads, and the host enforces that: the counter's datastore and directory expose only their read methods (plus realtime subscriptions) and notification mutes only get/list, while writes, typing signals, payments, notifications.send, files, assets, AI agents, translation, link previews, device capabilities, identification and account actions all answer as unavailable. It also renders nothing, navigates nowhere, emits no events or toasts, marks nothing read, and calls none of usePageBadge, useScreenTitle, useSectionEmpty or useWidgetRoute's setter. The linter refuses a declared counter whose entry has no useBadgeCount export. The AppStudio widget agent leaves this unset: a generated widget never declares a badge counter.",
+    default: false,
+  },
   events: {
     type: "object[]",
     required: true,
@@ -5301,7 +5311,14 @@ const CONTRACT = deepFreeze({
   //    flat `assets/` directory (`bundledAssets`, within `packageMaxBytes`).
   //    New `useBundledAsset(fileName)` resolves one through the new
   //    `widget.assets` map; linter rule `bundled-asset-missing` (error).
-  version: "1.159.0",
+  // 1.160.0: additive (sc-10829) — optional manifest field `badgeCounter`:
+  //    the entry exports `useBadgeCount(props)` (name in `badgeCounterExport`)
+  //    and the host runs it while the widget's page is closed, so the page
+  //    badge stays live; the host gives a counter a read-only context.
+  //    `usePageBadge(null)` now means "not known yet" and keeps the current
+  //    badge; `undefined` still clears it. Linter rules `badge-counter-export-missing`
+  //    (error) and `badge-counter-undeclared` (warning).
+  version: "1.160.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,
@@ -5327,6 +5344,8 @@ const CONTRACT = deepFreeze({
   themeWidgetStyles: THEME_WIDGET_STYLES,
   widgetContextShape: WIDGET_CONTEXT_SHAPE,
   bundleExportContract: BUNDLE_EXPORT_CONTRACT,
+  // sc-10829 — the hook a `badgeCounter: true` entry exports by name.
+  badgeCounterExport: "useBadgeCount",
   bannedApis: BANNED_APIS,
   vettedImports: VETTED_IMPORTS,
   allowedBareImports: ALLOWED_BARE_IMPORTS,