@colixsystems/widget-sdk 0.165.0 → 0.167.0

package/README.md

@@ -73,7 +73,31 @@ 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)
+
+**A bound colour can be translucent (sc-8893).** Binding and transparency were mutually exclusive: the Studio hid the opacity control the moment a colour field bound to a brand token, so an author who wanted "our brand colour at 20%" had to abandon the binding and freeze today's hex — which then stopped following a rebrand, the very thing binding exists to prevent.
+
+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.
+- **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.
+- **Fully additive.** Every stored binding is unsuffixed, parses as before, and renders byte-identically.
 
 ### What's new in 0.165.0 (contract 1.127.0 — unchanged)
 

package/dist/contract.cjs

@@ -192,20 +192,64 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
-// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
-// value and declared beside the allowlist it reads. Three readers have to agree
-// on what a binding IS: the Studio's colour picker writes one, both hosts
-// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// sc-8326 — the `theme:<path>` value grammar, as a PARSE over a STORED value
+// and declared beside the allowlist it reads. Three readers have to agree on
+// what a binding IS: the Studio's colour picker writes one, both hosts resolve
+// one, and Mason's plan validator must accept one as a gradient stop.
 // One definition, so they cannot drift (CLAUDE.md §3).
 const THEME_TOKEN_REF_PREFIX = "theme:";
 
+// sc-8893 — a binding may carry an OPACITY, `theme:<path>/<percent>`. Without
+// it an author had to choose between a colour that follows the workspace brand
+// and one they could make translucent; "our brand colour at 20%" was only
+// expressible by freezing today's hex, which then stopped following a rebrand.
+// `/` cannot occur in a token path, so an unsuffixed binding parses exactly as
+// it always did and no stored value changes meaning.
+const THEME_TOKEN_ALPHA_SEPARATOR = "/";
+const ALPHA_OPAQUE = 100;
+
+/**
+ * Parse a stored binding into `{ path, alpha }`, or `null` when the value is
+ * not one.
+ *
+ * `alpha` is `null` for an UNSUFFIXED binding, which inherits whatever opacity
+ * the token itself carries — a brand colour may be authored translucent, and
+ * reading the bare form as 100 would silently paint it solid. A suffix is the
+ * author's own opacity and REPLACES the token's, so `/100` is a real value: it
+ * is how "opaque, whatever the brand does" is expressed.
+ */
+function parseThemeColorTokenRef(value) {
+  if (typeof value !== "string") return null;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return null;
+  const body = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  const cut = body.indexOf(THEME_TOKEN_ALPHA_SEPARATOR);
+  const path = cut === -1 ? body : body.slice(0, cut);
+  if (!THEME_COLOR_TOKENS.some((token) => token.path === path)) return null;
+  if (cut === -1) return { path, alpha: null };
+  const percent = body.slice(cut + 1);
+  // One spelling per opacity: no leading zeros, nothing above 100. A malformed
+  // suffix reads as "not a binding", so the field falls back to its default
+  // rather than painting a half-parsed colour.
+  if (!/^(?:0|[1-9]\d{0,2})$/.test(percent)) return null;
+  const alpha = Number(percent);
+  return alpha > ALPHA_OPAQUE ? null : { path, alpha };
+}
+
 function isThemeColorTokenRef(value) {
-  if (typeof value !== "string") return false;
-  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
-  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
-  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+  return parseThemeColorTokenRef(value) !== null;
 }
 
+/**
+ * Spell one binding. `percent` of `null`/`undefined` writes the bare form — the
+ * binding that defers to the token's own opacity. The path is the caller's to
+ * take from `CONTRACT.themeColorTokens`; an unlisted one spells a string this
+ * module's own parse rejects.
+ */
+function formatThemeColorTokenRef(path, percent) {
+  const ref = `${THEME_TOKEN_REF_PREFIX}${path}`;
+  if (percent === null || percent === undefined) return ref;
+  return `${ref}${THEME_TOKEN_ALPHA_SEPARATOR}${clampAlphaPercent(percent)}`;
+}
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -1414,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>",
@@ -2221,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,
   },
@@ -4483,7 +4533,27 @@ const CONTRACT = deepFreeze({
   //    and form field so every widget draws them from one implementation, plus
   //    a `height` token on the `muted` scope. Additive: the built-ins render
   //    exactly as before.
-  version: "1.127.0",
+  // 1.128.0: additive (sc-8893) — a `theme:` colour binding may carry an
+  //    OPACITY, `theme:<path>/<percent>`. Binding and transparency used to be
+  //    mutually exclusive: the Studio hid the opacity control the moment a
+  //    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
+  //    `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
+  //    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.
+  // 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,
@@ -4560,6 +4630,59 @@ function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+// sc-8893 — opacity as an authored PERCENTAGE, converted here and nowhere else.
+// The Studio's opacity control and the host's binding resolver both spell a
+// colour's alpha through these, so the 20% a panel reads back is the 20% a
+// render paints. 255/100 > 1, so percent → byte is injective and the inverse
+// below is exact.
+function clampAlphaPercent(value) {
+  const n = Math.round(Number(value));
+  // Unparseable reads as fully opaque: "cannot tell" must never turn a surface
+  // see-through on its own.
+  if (!Number.isFinite(n)) return ALPHA_OPAQUE;
+  return Math.min(ALPHA_OPAQUE, Math.max(0, n));
+}
+
+function expandShortHex(hex) {
+  const body = hex.slice(1);
+  if (body.length > 4) return hex;
+  return `#${[...body].map((c) => c + c).join("")}`;
+}
+
+/**
+ * Apply `percent` opacity to a hex colour, returning `#RRGGBBAA` — or a plain
+ * `#RRGGBB` at full opacity, so an opaque colour is never rewritten with a
+ * redundant `ff`. A non-hex colour cannot carry alpha without being rewritten
+ * into another notation, so it is returned untouched rather than invented.
+ *
+ * "Hex" is `isHexColor`'s grammar — 3, 6 or 8 digits. The 4-digit `#RGBA` form
+ * is deliberately outside it (a gradient stop may not smuggle one past the
+ * injection guard), so it is returned untouched here too.
+ */
+function withHexAlpha(hex, percent) {
+  if (!isHexColor(hex)) return hex;
+  const base = expandShortHex(hex).slice(0, 7);
+  const alpha = clampAlphaPercent(percent);
+  if (alpha === ALPHA_OPAQUE) return base;
+  return `${base}${Math.round((alpha * 255) / 100)
+    .toString(16)
+    .padStart(2, "0")}`;
+}
+
+/**
+ * Read a hex colour's opacity back as a percentage. No alpha pair is 100.
+ *
+ * The percentage is lossy in this direction — 255 alpha values map onto 101
+ * percentages — so a near-opaque `fe` reads back as 100. Only a value this
+ * function produced round-trips exactly.
+ */
+function hexAlphaPercent(hex) {
+  if (!isHexColor(hex)) return ALPHA_OPAQUE;
+  const full = expandShortHex(hex);
+  if (full.length !== 9) return ALPHA_OPAQUE;
+  return Math.round((parseInt(full.slice(7), 16) * 100) / 255);
+}
+
 /**
  * The R/G/B bytes, with any alpha pair IGNORED.
  *
@@ -4788,7 +4911,11 @@ module.exports = {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/contract.js

@@ -192,20 +192,64 @@ const THEME_COLOR_TOKENS = Object.freeze([
   Object.freeze({ path: "colors.secondary", label: "Secondary" }),
 ]);
 
-// sc-8326 — the `theme:<path>` value grammar, as a PREDICATE over a STORED
-// value and declared beside the allowlist it reads. Three readers have to agree
-// on what a binding IS: the Studio's colour picker writes one, both hosts
-// resolve one, and Mason's plan validator must accept one as a gradient stop.
+// sc-8326 — the `theme:<path>` value grammar, as a PARSE over a STORED value
+// and declared beside the allowlist it reads. Three readers have to agree on
+// what a binding IS: the Studio's colour picker writes one, both hosts resolve
+// one, and Mason's plan validator must accept one as a gradient stop.
 // One definition, so they cannot drift (CLAUDE.md §3).
 const THEME_TOKEN_REF_PREFIX = "theme:";
 
+// sc-8893 — a binding may carry an OPACITY, `theme:<path>/<percent>`. Without
+// it an author had to choose between a colour that follows the workspace brand
+// and one they could make translucent; "our brand colour at 20%" was only
+// expressible by freezing today's hex, which then stopped following a rebrand.
+// `/` cannot occur in a token path, so an unsuffixed binding parses exactly as
+// it always did and no stored value changes meaning.
+const THEME_TOKEN_ALPHA_SEPARATOR = "/";
+const ALPHA_OPAQUE = 100;
+
+/**
+ * Parse a stored binding into `{ path, alpha }`, or `null` when the value is
+ * not one.
+ *
+ * `alpha` is `null` for an UNSUFFIXED binding, which inherits whatever opacity
+ * the token itself carries — a brand colour may be authored translucent, and
+ * reading the bare form as 100 would silently paint it solid. A suffix is the
+ * author's own opacity and REPLACES the token's, so `/100` is a real value: it
+ * is how "opaque, whatever the brand does" is expressed.
+ */
+function parseThemeColorTokenRef(value) {
+  if (typeof value !== "string") return null;
+  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return null;
+  const body = value.slice(THEME_TOKEN_REF_PREFIX.length);
+  const cut = body.indexOf(THEME_TOKEN_ALPHA_SEPARATOR);
+  const path = cut === -1 ? body : body.slice(0, cut);
+  if (!THEME_COLOR_TOKENS.some((token) => token.path === path)) return null;
+  if (cut === -1) return { path, alpha: null };
+  const percent = body.slice(cut + 1);
+  // One spelling per opacity: no leading zeros, nothing above 100. A malformed
+  // suffix reads as "not a binding", so the field falls back to its default
+  // rather than painting a half-parsed colour.
+  if (!/^(?:0|[1-9]\d{0,2})$/.test(percent)) return null;
+  const alpha = Number(percent);
+  return alpha > ALPHA_OPAQUE ? null : { path, alpha };
+}
+
 function isThemeColorTokenRef(value) {
-  if (typeof value !== "string") return false;
-  if (!value.startsWith(THEME_TOKEN_REF_PREFIX)) return false;
-  const path = value.slice(THEME_TOKEN_REF_PREFIX.length);
-  return THEME_COLOR_TOKENS.some((token) => token.path === path);
+  return parseThemeColorTokenRef(value) !== null;
 }
 
+/**
+ * Spell one binding. `percent` of `null`/`undefined` writes the bare form — the
+ * binding that defers to the token's own opacity. The path is the caller's to
+ * take from `CONTRACT.themeColorTokens`; an unlisted one spells a string this
+ * module's own parse rejects.
+ */
+function formatThemeColorTokenRef(path, percent) {
+  const ref = `${THEME_TOKEN_REF_PREFIX}${path}`;
+  if (percent === null || percent === undefined) return ref;
+  return `${ref}${THEME_TOKEN_ALPHA_SEPARATOR}${clampAlphaPercent(percent)}`;
+}
 
 // REQ-THEME-15 (sc-1497) — per-component style tokens. The global palette is a
 // single lever: remapping `primaryColor` to recolour "the buttons" recolours
@@ -1414,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>",
@@ -2221,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,
   },
@@ -4479,7 +4529,27 @@ const CONTRACT = deepFreeze({
   //    and form field so every widget draws them from one implementation, plus
   //    a `height` token on the `muted` scope. Additive: the built-ins render
   //    exactly as before.
-  version: "1.127.0",
+  // 1.128.0: additive (sc-8893) — a `theme:` colour binding may carry an
+  //    OPACITY, `theme:<path>/<percent>`. Binding and transparency used to be
+  //    mutually exclusive: the Studio hid the opacity control the moment a
+  //    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
+  //    `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
+  //    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.
+  // 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,
@@ -4556,6 +4626,59 @@ function isHexColor(value) {
   return typeof value === "string" && HEX_RE.test(value);
 }
 
+// sc-8893 — opacity as an authored PERCENTAGE, converted here and nowhere else.
+// The Studio's opacity control and the host's binding resolver both spell a
+// colour's alpha through these, so the 20% a panel reads back is the 20% a
+// render paints. 255/100 > 1, so percent → byte is injective and the inverse
+// below is exact.
+function clampAlphaPercent(value) {
+  const n = Math.round(Number(value));
+  // Unparseable reads as fully opaque: "cannot tell" must never turn a surface
+  // see-through on its own.
+  if (!Number.isFinite(n)) return ALPHA_OPAQUE;
+  return Math.min(ALPHA_OPAQUE, Math.max(0, n));
+}
+
+function expandShortHex(hex) {
+  const body = hex.slice(1);
+  if (body.length > 4) return hex;
+  return `#${[...body].map((c) => c + c).join("")}`;
+}
+
+/**
+ * Apply `percent` opacity to a hex colour, returning `#RRGGBBAA` — or a plain
+ * `#RRGGBB` at full opacity, so an opaque colour is never rewritten with a
+ * redundant `ff`. A non-hex colour cannot carry alpha without being rewritten
+ * into another notation, so it is returned untouched rather than invented.
+ *
+ * "Hex" is `isHexColor`'s grammar — 3, 6 or 8 digits. The 4-digit `#RGBA` form
+ * is deliberately outside it (a gradient stop may not smuggle one past the
+ * injection guard), so it is returned untouched here too.
+ */
+function withHexAlpha(hex, percent) {
+  if (!isHexColor(hex)) return hex;
+  const base = expandShortHex(hex).slice(0, 7);
+  const alpha = clampAlphaPercent(percent);
+  if (alpha === ALPHA_OPAQUE) return base;
+  return `${base}${Math.round((alpha * 255) / 100)
+    .toString(16)
+    .padStart(2, "0")}`;
+}
+
+/**
+ * Read a hex colour's opacity back as a percentage. No alpha pair is 100.
+ *
+ * The percentage is lossy in this direction — 255 alpha values map onto 101
+ * percentages — so a near-opaque `fe` reads back as 100. Only a value this
+ * function produced round-trips exactly.
+ */
+function hexAlphaPercent(hex) {
+  if (!isHexColor(hex)) return ALPHA_OPAQUE;
+  const full = expandShortHex(hex);
+  if (full.length !== 9) return ALPHA_OPAQUE;
+  return Math.round((parseInt(full.slice(7), 16) * 100) / 255);
+}
+
 /**
  * The R/G/B bytes, with any alpha pair IGNORED.
  *
@@ -4784,7 +4907,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   formatMoneyIn,
   normaliseCurrencyCode,
   sameWidgetRouteValue,

package/dist/host.d.ts

@@ -434,7 +434,8 @@ export function isThemeTokenRef(value: unknown): boolean;
 /**
  * Resolve one `theme:<path>` binding against a resolved widget theme. Returns
  * `undefined` for a non-binding, a token outside `CONTRACT.themeColorTokens`,
- * or a path that does not resolve to a colour.
+ * or a path that does not resolve to a colour. A binding carrying an opacity
+ * (`theme:<path>/<percent>`, sc-8893) resolves to `#RRGGBBAA`.
  */
 export function resolveThemeTokenRef(
   value: unknown,

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.
@@ -2942,6 +2966,40 @@ export const THEME_TOKEN_REF_PREFIX: string;
  */
 export function isThemeColorTokenRef(value: unknown): boolean;
 
+export interface ThemeColorTokenRef {
+  path: string;
+  /** null for a bare binding, which inherits the token's own opacity. */
+  alpha: number | null;
+}
+
+/**
+ * sc-8893 — parse a binding into its token path and opacity percentage, or null
+ * when the value is not a binding. `theme:<path>` inherits whatever opacity the
+ * token carries; `theme:<path>/<percent>` replaces it with the author's.
+ */
+export function parseThemeColorTokenRef(
+  value: unknown,
+): ThemeColorTokenRef | null;
+
+/**
+ * sc-8893 — spell one binding. A `percent` of null/undefined writes the bare
+ * form, which defers to the token's own opacity.
+ */
+export function formatThemeColorTokenRef(
+  path: string,
+  percent?: unknown,
+): string;
+
+/**
+ * sc-8893 — apply an opacity percentage to a hex colour, returning `#RRGGBBAA`
+ * (or plain `#RRGGBB` at 100). A non-hex colour is returned untouched. Shared
+ * so the Studio's opacity control and the hosts' resolver convert identically.
+ */
+export function withHexAlpha(hex: string, percent: unknown): string;
+
+/** sc-8893 — read a hex colour's opacity back as a percentage (no alpha = 100). */
+export function hexAlphaPercent(hex: string): number;
+
 // Linter
 export interface LintFinding {
   rule: string;

package/dist/index.js

@@ -164,7 +164,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

package/dist/index.native.js

@@ -157,7 +157,11 @@ export {
   gradientAngleToVector,
   normaliseComponentGradient,
   isThemeColorTokenRef,
+  parseThemeColorTokenRef,
+  formatThemeColorTokenRef,
   THEME_TOKEN_REF_PREFIX,
+  withHexAlpha,
+  hexAlphaPercent,
   clampSpacingScale,
   scaleSpacing,
 } from "./contract.js";

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/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/dist/theme-token-refs.js

@@ -18,7 +18,11 @@
 // type today's hex, which went stale silently. A bound field stores the TOKEN,
 // so the intent survives the rebrand.
 
-import { isThemeColorTokenRef, THEME_TOKEN_REF_PREFIX } from "./contract.js";
+import {
+  parseThemeColorTokenRef,
+  withHexAlpha,
+  THEME_TOKEN_REF_PREFIX,
+} from "./contract.js";
 
 // A value is a binding, not a colour, when it carries this prefix. No CSS
 // colour can begin with it, so a stored literal can never be misread as one.
@@ -26,7 +30,15 @@ import { isThemeColorTokenRef, THEME_TOKEN_REF_PREFIX } from "./contract.js";
 // grammar from there, and two spellings of it would drift.
 const PREFIX = THEME_TOKEN_REF_PREFIX;
 
-/** True when `value` is a theme-token binding rather than a literal colour. */
+/**
+ * True when `value` is a theme-token binding rather than a literal colour.
+ *
+ * Deliberately the PREFIX alone, not the contract's full parse: the callers
+ * below use it to decide what to DROP, and a binding naming a withdrawn token
+ * or carrying a malformed opacity must go back to unset — where its
+ * `themeDefault` paints — rather than reach a renderer as the literal string
+ * `theme:...`.
+ */
 export function isThemeTokenRef(value) {
   return typeof value === "string" && value.startsWith(PREFIX);
 }
@@ -43,14 +55,16 @@ export function resolveThemeTokenRef(value, theme) {
   // The allowlist is the contract's, so what the Studio may WRITE and what a
   // host will RESOLVE cannot drift apart. sc-8326 moved the test itself there
   // too, since Mason's plan validator has to ask the same question.
-  if (!isThemeColorTokenRef(value)) return undefined;
-  const path = value.slice(PREFIX.length);
-  const resolved = path
+  const ref = parseThemeColorTokenRef(value);
+  if (!ref) return undefined;
+  const resolved = ref.path
     .split(".")
     .reduce((o, k) => (o == null ? undefined : o[k]), theme);
-  return typeof resolved === "string" && resolved.trim() !== ""
-    ? resolved
-    : undefined;
+  if (typeof resolved !== "string" || resolved.trim() === "") return undefined;
+  // sc-8893: an authored opacity REPLACES the token's. With none authored the
+  // token is handed back verbatim — including a token that is itself
+  // translucent, which reading the bare form as 100 would quietly make solid.
+  return ref.alpha === null ? resolved : withHexAlpha(resolved, ref.alpha);
 }
 
 function isPlainObject(value) {

package/package.json

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