@colixsystems/widget-sdk 0.166.0 → 0.168.0

package/README.md

@@ -73,7 +73,18 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.165.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.167.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.167.0 (contract 1.129.0)
+
+**The markdown grammar stops eating characters, and `useAgent` says to render a reply with `<RichText>` (sc-8891).** A model answers in markdown by default, so a chat surface that renders `message.content` in a plain `<Text>` shows an app user the raw markers. Pointing model text at `<RichText>` surfaced two grammar bugs that were corrupting **author** content too:
+
+- **Emphasis now follows CommonMark's flanking rules.** `_` no longer opens or closes inside a word and neither delimiter opens before whitespace, so `created_at` keeps its underscore and `2 * 4` keeps its asterisk. Previously both were silently deleted — in a newsfeed post as well as an AI reply.
+- **`<RichText>` gains `stripLegacyHtml`** (default `true`, unchanged for stored rows). The legacy-HTML strip removes every `<…>` as soon as one tag-shaped token appears, which ate `Promise<void>` and `<name@example.com>`. Pass **`false`** for text that was never an HTML row.
+- **Fenced ``` blocks render verbatim** in a monospace block, newlines and indentation intact. They used to collapse into one inline span with stray backticks.
+- A line that cannot hold a link skips the link pass, so a bracket-heavy string no longer costs seconds of main-thread time.
+
+Render an **assistant** message with `<RichText value={m.content} stripLegacyHtml={false} />`. Keep the **user's own** message a `<Text>` — someone who types `*maybe*` means asterisks.
 
 ### What's new in 0.166.0 (contract 1.128.0)
 
@@ -82,7 +93,7 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 A binding may now carry an opacity: `"theme:colors.primary/20"` is the primary brand colour at 20%.
 
 - **`parseThemeColorTokenRef(value)` / `formatThemeColorTokenRef(path, percent)`** publish the grammar beside the existing `isThemeColorTokenRef` predicate. The BARE form inherits whatever opacity the token itself carries — a workspace may author a translucent brand colour — so `/100` is a real value, not a redundant spelling: it is how "opaque, whatever the brand does" is said. One opacity has one spelling otherwise (no leading zeros, nothing above 100).
-- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion the Studio's opacity control and both hosts' resolver share, so the 20% a panel reads back is the 20% a render paints.
+- **`withHexAlpha(hex, percent)` / `hexAlphaPercent(hex)`** are the percent ↔ alpha-byte conversion, so the 20% a panel reads back is the 20% a render paints. The Studio's `frontend/src/utils/color.js` keeps its own copy of this maths rather than importing it — that module is reached by a `node --test` suite, and the SDK is a Vite alias with no node resolution — and the two are pinned equal by the SDK's suite.
 - **An authored opacity replaces the token's.** With none authored the token is handed back verbatim, including a token that is itself translucent — reading the bare form as 100 would quietly paint a see-through brand colour solid.
 - **A token resolving to a non-hex colour stays opaque** — alpha cannot be applied without rewriting the author's notation — and the Studio disables the opacity control for that case rather than lying about it.
 - **Nothing changes for a widget author.** The host still hands your code an ordinary colour string; it is simply `#RRGGBBAA` when an opacity was authored.

package/dist/contract.cjs

@@ -1458,6 +1458,12 @@ const HOOKS = [
       "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
       "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
+      "RENDER AN ASSISTANT REPLY WITH <RichText value={msg.content} />, " +
+      "not <Text>: a model answers in MARKDOWN by default — **bold**, " +
+      "`code`, # headings, - bullets, 1. numbered steps, tables — and a " +
+      "plain <Text> shows the raw markers to the app user, so a numbered " +
+      "how-to arrives as one unreadable line. The USER's own message " +
+      "stays <Text>: someone who types *maybe* means asterisks. " +
       "Reads ctx.agents.",
     returnShape: {
       send: "(text) => Promise<{ id, role, content, created_at } | null>",
@@ -2265,7 +2271,7 @@ const PRIMITIVES = [
   {
     name: "RichText",
     description:
-      'Formatted-content renderer. `<RichText value={record.body} />`. THE way to display text an app user wrote with formatting — bold, italic, inline code, `#`/`##`/`###` headings, `-` bullets, `1.` numbered items, `[label](target)` links, `| a | b |` pipe tables (a header row, a `| --- | --- |` divider, then body rows; `:--` / `--:` / `:-:` in a divider cell sets that column\'s alignment), and one-line `![alt](src "large")` images. `value` is markdown text, NOT HTML: widgets render through React Native primitives, which have no `dangerouslySetInnerHTML` on either host, so HTML inside a content string shows up as literal tag soup — never assemble content out of `<strong>`/`<br>`/`<table>` tags. Stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. A link is pressed through the host\'s `navigation.openLink`, which is what decides page / external / refuse — so a link target is just a string here: an absolute URL leaves the app, a bare page id or slug navigates inside it, and anything unfollowable (`javascript:`, a control character) is refused by that one resolver. Never pre-filter a target yourself and never route one through `Linking.openURL`, which performs anything. Props: `value` (markdown string), `renderImage` (optional `({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving those needs the scopes your own widget holds; without it only absolute http(s) URLs render), `followLinks` (default true; pass false to render links styled but inert, which is what an editing preview wants so a tap cannot discard the draft), `style`, `testID`. Colour, type scale and leading all come from the workspace theme — never re-style them. Table cells are equal-width columns whose text wraps, so a wide table stays inside the widget on a phone instead of scrolling sideways.',
+      'Formatted-content renderer. `<RichText value={record.body} />`. THE way to display text an app user wrote with formatting — bold, italic, inline code, `#`/`##`/`###` headings, `-` bullets, `1.` numbered items, `[label](target)` links, `| a | b |` pipe tables (a header row, a `| --- | --- |` divider, then body rows; `:--` / `--:` / `:-:` in a divider cell sets that column\'s alignment), and one-line `![alt](src "large")` images. `value` is markdown text, NOT HTML: widgets render through React Native primitives, which have no `dangerouslySetInnerHTML` on either host, so HTML inside a content string shows up as literal tag soup — never assemble content out of `<strong>`/`<br>`/`<table>` tags. Stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. A link is pressed through the host\'s `navigation.openLink`, which is what decides page / external / refuse — so a link target is just a string here: an absolute URL leaves the app, a bare page id or slug navigates inside it, and anything unfollowable (`javascript:`, a control character) is refused by that one resolver. Never pre-filter a target yourself and never route one through `Linking.openURL`, which performs anything. Fenced ```` ``` ```` blocks render verbatim in a monospace block, so a code sample keeps its newlines and indentation. Props: `value` (markdown string), `stripLegacyHtml` (default true — normalises a STORED row that still holds HTML; pass **false** for text that was never HTML, such as an AI reply, because the strip removes every `<…>` once any tag-shaped token appears and would eat `Promise<void>` or `<name@example.com>`), `renderImage` (optional `({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving those needs the scopes your own widget holds; without it only absolute http(s) URLs render), `followLinks` (default true; pass false to render links styled but inert, which is what an editing preview wants so a tap cannot discard the draft), `style`, `testID`. Colour, type scale and leading all come from the workspace theme — never re-style them. Table cells are equal-width columns whose text wraps, so a wide table stays inside the widget on a phone instead of scrolling sideways.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4533,15 +4539,21 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as
   //    before, so every stored value is untouched.
-  version: "1.128.0",
+  // 1.129.0: additive (sc-8891) — `<RichText>` gains `stripLegacyHtml`
+  // (default true) and renders fenced ``` blocks verbatim. The legacy-HTML
+  // strip exists for stored author rows; applied to text that was never HTML
+  // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
+  // emphasis grammar now follows CommonMark flanking rules, so `created_at`
+  // keeps its underscore and `2 * 4` keeps its asterisk.
+  version: "1.129.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1458,6 +1458,12 @@ const HOOKS = [
       "no error at all. Call cancel() to stop waiting -- it ends the WAIT, " +
       "not the turn. NEVER surface a " +
       "raw error or the workspace's billing state to an app user. " +
+      "RENDER AN ASSISTANT REPLY WITH <RichText value={msg.content} />, " +
+      "not <Text>: a model answers in MARKDOWN by default — **bold**, " +
+      "`code`, # headings, - bullets, 1. numbered steps, tables — and a " +
+      "plain <Text> shows the raw markers to the app user, so a numbered " +
+      "how-to arrives as one unreadable line. The USER's own message " +
+      "stays <Text>: someone who types *maybe* means asterisks. " +
       "Reads ctx.agents.",
     returnShape: {
       send: "(text) => Promise<{ id, role, content, created_at } | null>",
@@ -2265,7 +2271,7 @@ const PRIMITIVES = [
   {
     name: "RichText",
     description:
-      'Formatted-content renderer. `<RichText value={record.body} />`. THE way to display text an app user wrote with formatting — bold, italic, inline code, `#`/`##`/`###` headings, `-` bullets, `1.` numbered items, `[label](target)` links, `| a | b |` pipe tables (a header row, a `| --- | --- |` divider, then body rows; `:--` / `--:` / `:-:` in a divider cell sets that column\'s alignment), and one-line `![alt](src "large")` images. `value` is markdown text, NOT HTML: widgets render through React Native primitives, which have no `dangerouslySetInnerHTML` on either host, so HTML inside a content string shows up as literal tag soup — never assemble content out of `<strong>`/`<br>`/`<table>` tags. Stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. A link is pressed through the host\'s `navigation.openLink`, which is what decides page / external / refuse — so a link target is just a string here: an absolute URL leaves the app, a bare page id or slug navigates inside it, and anything unfollowable (`javascript:`, a control character) is refused by that one resolver. Never pre-filter a target yourself and never route one through `Linking.openURL`, which performs anything. Props: `value` (markdown string), `renderImage` (optional `({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving those needs the scopes your own widget holds; without it only absolute http(s) URLs render), `followLinks` (default true; pass false to render links styled but inert, which is what an editing preview wants so a tap cannot discard the draft), `style`, `testID`. Colour, type scale and leading all come from the workspace theme — never re-style them. Table cells are equal-width columns whose text wraps, so a wide table stays inside the widget on a phone instead of scrolling sideways.',
+      'Formatted-content renderer. `<RichText value={record.body} />`. THE way to display text an app user wrote with formatting — bold, italic, inline code, `#`/`##`/`###` headings, `-` bullets, `1.` numbered items, `[label](target)` links, `| a | b |` pipe tables (a header row, a `| --- | --- |` divider, then body rows; `:--` / `--:` / `:-:` in a divider cell sets that column\'s alignment), and one-line `![alt](src "large")` images. `value` is markdown text, NOT HTML: widgets render through React Native primitives, which have no `dangerouslySetInnerHTML` on either host, so HTML inside a content string shows up as literal tag soup — never assemble content out of `<strong>`/`<br>`/`<table>` tags. Stored text that still holds legacy HTML is stripped to plain text rather than shown as markup. A link is pressed through the host\'s `navigation.openLink`, which is what decides page / external / refuse — so a link target is just a string here: an absolute URL leaves the app, a bare page id or slug navigates inside it, and anything unfollowable (`javascript:`, a control character) is refused by that one resolver. Never pre-filter a target yourself and never route one through `Linking.openURL`, which performs anything. Fenced ```` ``` ```` blocks render verbatim in a monospace block, so a code sample keeps its newlines and indentation. Props: `value` (markdown string), `stripLegacyHtml` (default true — normalises a STORED row that still holds HTML; pass **false** for text that was never HTML, such as an AI reply, because the strip removes every `<…>` once any tag-shaped token appears and would eat `Promise<void>` or `<name@example.com>`), `renderImage` (optional `({ src, alt, size }) => node` — supply it when images are filestore ids, because resolving those needs the scopes your own widget holds; without it only absolute http(s) URLs render), `followLinks` (default true; pass false to render links styled but inert, which is what an editing preview wants so a tap cannot discard the draft), `style`, `testID`. Colour, type scale and leading all come from the workspace theme — never re-style them. Table cells are equal-width columns whose text wraps, so a wide table stays inside the widget on a phone instead of scrolling sideways.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -4529,15 +4535,21 @@ const CONTRACT = deepFreeze({
   //    field bound, so "our brand colour at 20%" forced the author back to a
   //    frozen hex, which then stopped following a rebrand — the exact thing
   //    binding exists to prevent. `parseThemeColorTokenRef` /
-  //    `formatThemeColorTokenRef` publish the grammar and
+  //    `formatThemeColorTokenRef` publish the grammar, and
   //    `withHexAlpha` / `hexAlphaPercent` the percent-to-byte conversion the
-  //    Studio's control and both hosts' resolver share, so 20% authored is 20%
-  //    painted. The BARE form inherits the token's own opacity (a brand colour
+  //    Studio's control and both hosts' resolver answer alike, so 20% authored
+  //    is 20% painted. The BARE form inherits the token's own opacity (a brand colour
   //    may be authored translucent), which makes `/100` a real value rather
   //    than a redundant spelling: it is how "opaque, whatever the brand does"
   //    is said. Additive: an unsuffixed binding parses and resolves exactly as
   //    before, so every stored value is untouched.
-  version: "1.128.0",
+  // 1.129.0: additive (sc-8891) — `<RichText>` gains `stripLegacyHtml`
+  // (default true) and renders fenced ``` blocks verbatim. The legacy-HTML
+  // strip exists for stored author rows; applied to text that was never HTML
+  // it removed every `<...>`, so an AI reply lost `Promise<void>`. The
+  // emphasis grammar now follows CommonMark flanking rules, so `created_at`
+  // keeps its underscore and `2 * 4` keeps its asterisk.
+  version: "1.129.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/host.js

@@ -74,6 +74,9 @@ export {
 // SIDEBAR local menu hangs in the rail and the drawer. The compiler asks it
 // once per screen at build time and the Player once per render, so the two
 // chromes derive the same tree from the same code.
+// REQ-NAV-LOCAL (sc-8901): `resolveLocalNavModel` answers WHICH model a page
+// wears in one device view, so the same menu can be a bottom bar on a phone and
+// unfold in the rail on a desktop.
 export {
   normaliseNavigation,
   menuItemCap,
@@ -94,6 +97,8 @@ export {
   DEFAULT_TOP_STRIPE_HEIGHT_PX,
   DEFAULT_TOP_STRIPE_PADDING_X_PX,
   resolveSidebarUnfold,
+  resolveLocalNavModel,
+  drawsLocalNavAnywhere,
 } from "./navigation.js";
 
 // sc-5717: the codec behind `useWidgetRoute()` — how a widget's own internal

package/dist/index.d.ts

@@ -1221,6 +1221,7 @@ export interface AgentMessage {
   conversation_id: string;
   /** The system prompt is NOT part of the transcript — it lives on the agent. */
   role: "user" | "assistant";
+  /** Markdown — an assistant answers in it. Render with `<RichText>`. */
   content: string;
   /**
    * sc-8332 — what the agent DID on this turn, for the person to see. Present
@@ -2767,17 +2768,35 @@ export type MarkdownBlock =
   | { type: "paragraph"; spans: MarkdownSpan[] }
   | { type: "bullet"; marker: string; spans: MarkdownSpan[] }
   | { type: "ordered"; marker: string; spans: MarkdownSpan[] }
-  | { type: "image"; src: string; alt: string; size: MarkdownImageSize };
+  | { type: "image"; src: string; alt: string; size: MarkdownImageSize }
+  /** A fenced ``` block. `text` is verbatim, newlines and indentation intact. */
+  | { type: "code"; text: string; lang: string };
 
 export type MarkdownImageSize = "small" | "medium" | "large" | "full";
 
 export const MARKDOWN_IMAGE_SIZES: readonly MarkdownImageSize[];
 
 /** Parses the markdown subset into blocks. Non-string input yields `[]`. */
-export function parseMarkdown(text: unknown): MarkdownBlock[];
+export function parseMarkdown(
+  text: unknown,
+  options?: MarkdownParseOptions,
+): MarkdownBlock[];
+
+export interface MarkdownParseOptions {
+  /**
+   * Normalise a STORED row that still holds HTML (default true). Pass false
+   * for text that was never HTML — an AI reply, say — because the strip
+   * removes every `<…>` once any tag-shaped token appears, which would eat
+   * `Promise<void>` and `<name@example.com>`.
+   */
+  stripLegacyHtml?: boolean;
+}
 
 /** Marker-free projection of `text`, for search, previews and a11y labels. */
-export function markdownToPlainText(text: unknown): string;
+export function markdownToPlainText(
+  text: unknown,
+  options?: MarkdownParseOptions,
+): string;
 
 /** Reads one line as an image block, or `null` when it is not one. */
 export function parseMarkdownImage(
@@ -2824,6 +2843,11 @@ export function normaliseMarkdownImageSize(size: unknown): MarkdownImageSize;
 export const RichText: (props: {
   /** Markdown text. Legacy HTML is stripped to plain text, never rendered. */
   value?: string;
+  /**
+   * See `MarkdownParseOptions.stripLegacyHtml` (default true). Pass false for
+   * text that was never an HTML row, such as an AI agent's reply.
+   */
+  stripLegacyHtml?: boolean;
   /**
    * Resolves an image block to a node. Supply it when images are filestore
    * ids — without it only absolute http(s) URLs render.

package/dist/markdown.js

@@ -155,14 +155,53 @@ function linkSpans(rawLabel, href) {
   return spans.some((span) => span.text) ? spans : [{ text: href, href }];
 }
 
+// CommonMark's flanking rules. Without them `created_at` loses its underscore
+// and `2 * 4` loses its asterisk -- silent character deletion in ordinary
+// prose, which an agent's reply has no author around to notice and correct.
+// ASCII punctuation rather than \p{P}: Hermes is the native engine and a
+// word char here is anything that is neither space nor punctuation, so an
+// accented letter still counts as intraword.
+const ASCII_PUNCT_RE = /[!-/:-@[-`{-~]/;
+
+function isWordChar(char) {
+  return char !== "" && !/\s/.test(char) && !ASCII_PUNCT_RE.test(char);
+}
+
+// `delim` may open only when the run is not followed by whitespace, and `_`
+// additionally may not open or close inside a word.
+function emphasisFlanks(delim, content, source, openAt, closeEnd) {
+  if (content === "") return false;
+  if (/\s/.test(content.charAt(0))) return false;
+  if (/\s/.test(content.charAt(content.length - 1))) return false;
+  if (delim !== "_") return true;
+  const before = openAt > 0 ? source.charAt(openAt - 1) : "";
+  const after = source.charAt(closeEnd);
+  return !isWordChar(before) && !isWordChar(after);
+}
+
+// Alternation order matters: `**` must be tried before `*`, or the bold
+// marker is consumed as two italics. Group numbers are shared by both so the
+// branch handling below reads the same match indices either way.
+const LINK_PATTERN =
+  /(!?)\[((?:[^\]\\]|\\.)*)\]\(\s*(\S+?)\s*\)|(\*\*)(.+?)\4|(`)([^`]+?)\6|([*_])(.+?)\8/g;
+// Same groups so the branch handling reads identical match indices; the link
+// alternative is `[^\s\S]`, which can never match, so it is skipped for free.
+const PLAIN_PATTERN =
+  /(!?)([^\s\S])([^\s\S])|(\*\*)(.+?)\4|(`)([^`]+?)\6|([*_])(.+?)\8/g;
+
 /** Splits one line into `{ text, bold?, italic?, code?, href? }` spans. */
 function parseInline(line) {
   const source = typeof line === "string" ? line : "";
   const spans = [];
   // One pass over the four delimiters. Alternation order matters: `**` must
   // be tried before `*` or the bold marker is consumed as two italics.
-  const pattern =
-    /(!?)\[((?:[^\]\\]|\\.)*)\]\(\s*(\S+?)\s*\)|(\*\*)(.+?)\4|(`)([^`]+?)\6|([*_])(.+?)\8/g;
+  // The link branch scans forward from EVERY `[`, so a line carrying many
+  // unclosed brackets costs O(n x brackets) -- 4s for 50k of them, a frozen
+  // JS thread. A link needs `](`, so a line without one skips that branch
+  // entirely and stays linear. Same spans either way.
+  const mayHoldLink = source.includes("](") && source.includes(")");
+  const pattern = mayHoldLink ? LINK_PATTERN : PLAIN_PATTERN;
+  pattern.lastIndex = 0;
   let cursor = 0;
   let match = pattern.exec(source);
   while (match) {
@@ -174,14 +213,37 @@ function parseInline(line) {
       // literal text rather than becoming a link to the image.
       if (match[1]) spans.push({ text: match[0] });
       else for (const span of linkSpans(match[2], match[3])) spans.push(span);
-    } else if (match[4]) spans.push({ text: match[5], bold: true });
-    else if (match[6]) spans.push({ text: match[7], code: true });
-    else spans.push({ text: match[9], italic: true });
+    } else if (match[4] || match[8]) {
+      const delim = match[4] || match[8];
+      const content = match[4] ? match[5] : match[9];
+      const closeEnd = match.index + match[0].length;
+      if (!emphasisFlanks(delim, content, source, match.index, closeEnd)) {
+        // Not emphasis after all: keep the delimiter as text and rescan from
+        // just after it, so a later legitimate pair can still match.
+        spans.push({ text: delim });
+        cursor = match.index + delim.length;
+        pattern.lastIndex = cursor;
+        match = pattern.exec(source);
+        continue;
+      }
+      if (match[4]) spans.push({ text: content, bold: true });
+      else spans.push({ text: content, italic: true });
+    } else if (match[6]) spans.push({ text: match[7], code: true });
     cursor = match.index + match[0].length;
     match = pattern.exec(source);
   }
   if (cursor < source.length) spans.push({ text: source.slice(cursor) });
-  return spans.length > 0 ? spans : [{ text: source }];
+  if (spans.length === 0) return [{ text: source }];
+  // A rejected delimiter leaves plain fragments either side of it; fold them
+  // back so a line of prose stays one span instead of three.
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    const plain = (s) => !s.bold && !s.italic && !s.code && !s.href;
+    if (last && plain(last) && plain(span)) last.text += span.text;
+    else merged.push({ ...span });
+  }
+  return merged;
 }
 
 // `\|` is how a literal pipe survives inside a cell, so the split has to walk
@@ -263,11 +325,22 @@ export function formatMarkdownTable(columns = 3, rows = 2) {
 /**
  * Parses markdown text into renderable blocks:
  * `{ type: "heading"|"paragraph"|"bullet"|"ordered", level?, marker?, spans }`,
- * `{ type: "image", src, alt, size }`, or
+ * `{ type: "image", src, alt, size }`,
+ * `{ type: "code", text, lang }`, or
  * `{ type: "table", rows: [{ header, cells: spans[] }], align }`.
+ *
+ * `stripLegacyHtml` (default true) normalises stored rows that still hold HTML.
+ * Pass false for text that was never HTML -- a model's reply, say -- because
+ * the strip removes EVERY `<...>` once any tag-shaped token appears, which
+ * silently eats `Promise<void>` and `<name@example.com>`.
  */
-export function parseMarkdown(text) {
-  const source = stripHtmlToMarkdown(text);
+export function parseMarkdown(text, options) {
+  const stripLegacy = options?.stripLegacyHtml !== false;
+  const source = stripLegacy
+    ? stripHtmlToMarkdown(text)
+    : typeof text === "string"
+      ? text
+      : "";
   if (!source.trim()) return [];
 
   const blocks = [];
@@ -284,6 +357,27 @@ export function parseMarkdown(text) {
   const lines = source.split(/\r?\n/);
   for (let i = 0; i < lines.length; i += 1) {
     const line = lines[i].trimEnd();
+
+    // A fenced block is verbatim: its newlines and indentation ARE the content,
+    // and joining them into a paragraph made a code sample unreadable.
+    const fence = /^\s*```+\s*([^`]*)$/.exec(line);
+    if (fence) {
+      flushParagraph();
+      const body = [];
+      let j = i + 1;
+      while (j < lines.length && !/^\s*```+\s*$/.test(lines[j])) {
+        body.push(lines[j]);
+        j += 1;
+      }
+      blocks.push({
+        type: "code",
+        text: body.join("\n"),
+        lang: fence[1].trim(),
+      });
+      i = j;
+      continue;
+    }
+
     if (!line.trim()) {
       flushParagraph();
       continue;
@@ -344,10 +438,11 @@ function spansToText(spans) {
 }
 
 /** Plain-text projection — used for search, previews, and a11y labels. */
-export function markdownToPlainText(text) {
-  return parseMarkdown(text)
+export function markdownToPlainText(text, options) {
+  return parseMarkdown(text, options)
     .map((block) => {
       if (block.type === "image") return block.alt;
+      if (block.type === "code") return block.text;
       // A table has no `spans` of its own; one line per row keeps a search
       // match and a screen reader reading the cells in their visual order.
       if (block.type === "table") {

package/dist/navigation.cjs

@@ -675,6 +675,64 @@ function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number
@@ -711,4 +769,4 @@ function borderWidthOr(...values) {
   return BORDER_WIDTH_MIN;
 }
 
-module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold };
+module.exports = { normaliseNavigation, menuItemCap, resolveFooterTokens, resolveSidebarTokens, resolveTopStripeLayout, resolveTopBarTokens, topStripeShowKey, TOP_STRIPE_ALWAYS_SHOWN_SLOTS, TOP_STRIPE_SLOTS, MIN_TOP_STRIPE_HEIGHT_PX, MAX_TOP_STRIPE_HEIGHT_PX, MIN_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_PADDING_X_PX, MAX_TOP_STRIPE_OFFSET_Y_PX, DEFAULT_TOP_STRIPE_HEIGHT_PX, DEFAULT_TOP_STRIPE_PADDING_X_PX, resolveSidebarUnfold, resolveLocalNavModel, drawsLocalNavAnywhere };

package/dist/navigation.js

@@ -666,6 +666,64 @@ export function resolveSidebarUnfold(input) {
   return { under: section.key, items: marked, standalone: true };
 }
 
+/**
+ * REQ-NAV-LOCAL (sc-8901) — which local-navigation model a page wears in ONE
+ * device view, so the same saved menu can be a bottom bar on a phone and unfold
+ * in the rail on a desktop.
+ *
+ * `local_nav` is the MOBILE value and the base of the cascade: a page authored
+ * before the wider views existed leaves both of them unset and therefore
+ * renders identically at every width. The cascade is REQ-LAY-07's — the one the
+ * layout grid and every responsive widget prop already use — because a page's
+ * chrome and its content must not disagree about what a tablet is.
+ *
+ * The vocabulary stays the API's: any non-empty string is a model and the
+ * host's own switch decides what it can draw, so a kind a newer backend allows
+ * cascades correctly here instead of being flattened to `NONE` on the way.
+ *
+ * @param {object|null|undefined} page — a page row carrying `local_nav` and,
+ *   optionally, `local_nav_tablet` / `local_nav_desktop`.
+ * @param {"mobile"|"tablet"|"desktop"} view — the device view being drawn.
+ * @returns {string} the model for that view; `NONE` when the page sets none.
+ */
+export function resolveLocalNavModel(page, view) {
+  const at = (key) => {
+    const value = isPlainObject(page) ? page[key] : null;
+    return typeof value === "string" && value ? value : null;
+  };
+  const mobile = at("local_nav") || "NONE";
+  if (view === "desktop") {
+    return at("local_nav_desktop") || at("local_nav_tablet") || mobile;
+  }
+  if (view === "tablet") return at("local_nav_tablet") || mobile;
+  return mobile;
+}
+
+// sc-8901: the three device views a local bar can differ across — REQ-LAY-07's
+// own list, so a page's chrome and its content classify a width alike. Ordered
+// narrowest first, which is also the cascade's direction.
+const LOCAL_NAV_VIEWS = ["mobile", "tablet", "desktop"];
+
+/**
+ * REQ-NAV-LOCAL (sc-8901) — does this page draw a local bar in ANY device view?
+ *
+ * The saved-menu reference is shared by all three views, so it is required — and
+ * resolved onto the wire — as soon as one of them draws. Asking
+ * `local_nav !== "NONE"` alone would miss a page that carries a bar only on the
+ * wider views.
+ *
+ * Beside the cascade it is derived from, so the API rule, the export's screen
+ * bake and Copy Workspace cannot disagree about which pages have a bar.
+ *
+ * @param {object|null|undefined} page — a page row.
+ * @returns {boolean}
+ */
+export function drawsLocalNavAnywhere(page) {
+  return LOCAL_NAV_VIEWS.some(
+    (view) => resolveLocalNavModel(page, view) !== "NONE",
+  );
+}
+
 // REQ-THEME-LOOK: the divider's width in px, bounded HERE so both hosts inherit
 // one range. The export clamped it on its way into the StyleSheet
 // (`coerceBorderWidth(...) ?? 1`) where the Player passed any finite number

package/dist/richtext-view.js

@@ -126,13 +126,23 @@ export function makeRichText(rn) {
     );
   }
 
-  function RichText({ value, renderImage, followLinks = true, style, testID }) {
+  function RichText({
+    value,
+    renderImage,
+    followLinks = true,
+    stripLegacyHtml = true,
+    style,
+    testID,
+  }) {
     const theme = useHostTheme();
     // The non-throwing reader, so RichText stays renderable outside a widget
     // host (a Studio preview, a test) the way DateTimePicker does.
     const navigation = useHostNavigation();
     const tokens = React.useMemo(() => resolveRichTextTokens(theme), [theme]);
-    const blocks = React.useMemo(() => parseMarkdown(value), [value]);
+    const blocks = React.useMemo(
+      () => parseMarkdown(value, { stripLegacyHtml }),
+      [value, stripLegacyHtml],
+    );
 
     // sc-7349: `openLink` is the platform's ONE link resolver — it decides page
     // / external / refuse, so a stored `javascript:` target can never be
@@ -157,6 +167,38 @@ export function makeRichText(rn) {
       View,
       { style, testID },
       blocks.map((block, i) => {
+        const gap = i === blocks.length - 1 ? 0 : tokens.blockGap;
+
+        if (block.type === "code") {
+          return React.createElement(
+            View,
+            {
+              key: i,
+              style: {
+                backgroundColor: tokens.surface,
+                borderColor: tokens.border,
+                borderWidth: 1,
+                borderRadius: 6,
+                padding: 8,
+                marginBottom: gap,
+              },
+            },
+            React.createElement(
+              Text,
+              {
+                style: {
+                  // The theme carries no mono token, as the inline span notes.
+                  fontFamily: "monospace",
+                  fontSize: tokens.codeSize,
+                  lineHeight: Math.round(tokens.codeSize * 1.5),
+                  color: tokens.color,
+                },
+              },
+              block.text,
+            ),
+          );
+        }
+
         if (block.type === "table") {
           return React.createElement(TableBlock, {
             key: i,
@@ -185,6 +227,7 @@ export function makeRichText(rn) {
                   fontWeight: "700",
                   fontSize: tokens.headingSizes[block.level] || tokens.headingSizes[3],
                   lineHeight: undefined,
+                  marginBottom: gap,
                 },
               ],
             },
@@ -196,7 +239,7 @@ export function makeRichText(rn) {
           if (typeof renderImage === "function") {
             return React.createElement(
               View,
-              { key: i, style: { marginBottom: tokens.blockGap } },
+              { key: i, style: { marginBottom: gap } },
               renderImage(block),
             );
           }
@@ -207,7 +250,7 @@ export function makeRichText(rn) {
             {
               key: i,
               style: {
-                marginBottom: tokens.blockGap,
+                marginBottom: gap,
                 width: tokens.imageWidth[block.size] || tokens.imageWidth.full,
               },
             },
@@ -243,7 +286,7 @@ export function makeRichText(rn) {
         if (block.type === "bullet" || block.type === "ordered") {
           return React.createElement(
             View,
-            { key: i, style: { flexDirection: "row" } },
+            { key: i, style: { flexDirection: "row", marginBottom: gap } },
             React.createElement(
               Text,
               {
@@ -254,11 +297,19 @@ export function makeRichText(rn) {
               },
               block.marker,
             ),
-            React.createElement(Text, { style: [paragraph, { flex: 1 }] }, spans),
+            React.createElement(
+              Text,
+              { style: [paragraph, { flex: 1, marginBottom: 0 }] },
+              spans,
+            ),
           );
         }
 
-        return React.createElement(Text, { key: i, style: paragraph }, spans);
+        return React.createElement(
+          Text,
+          { key: i, style: [paragraph, { marginBottom: gap }] },
+          spans,
+        );
       }),
     );
   }

package/package.json

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