Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(ui): render inline <img> runs in rich text

yhh1cb9303b93d1
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/guides/ui-text.mdx
index f5edc15ac..39cf240d0 100644
--- a/docs/astro/src/content/docs/guides/ui-text.mdx
+++ b/docs/astro/src/content/docs/guides/ui-text.mdx
@@ -133,7 +133,7 @@ known tag renders literally (so a stray `<` cannot eat your text).
| `<i>…</i>` | Italic run. |
| `<color=#RRGGBB>…</color>` | Colored run; `#RRGGBBAA` adds alpha. |
| `<font size=32>…</font>` | Run at another font size (`size="32"` also parses); the shared baseline is kept. |
-| `<img src="…" width=24 height=24 />` | Inline image segment — parsed today, **not yet rendered** (see below). |
+| `<img src="…" width=24 height=24 />` | Inline image — an icon flowed in with the text (see [below](#inline-images)). |
```typescript
import { defineSystem, addStartupSystem, GetWorld, spawnUIEntity, px } from 'esengine';
@@ -156,12 +156,21 @@ The parser is exported as `parseRichText(input)`, returning `RichTextRun[]` —
`TextSegment` (`text`, `bold`, `italic`, `color`, `fontSize`) or `ImageSegment`
per run — if you want to drive a custom pipeline from the same markup.
-<Aside type="caution">
- `<img src="…" width=N height=N valign=baseline|middle|top|bottom offsetX=N
- offsetY=N scale=N tint=#RRGGBB />` parses into an `ImageSegment` (the tag must
- be self-closing and needs `src`), but the built-in text renderer currently
- **skips image runs** — inline sprites in text do not draw yet. Compose an
- image next to the text with flexbox instead.
+## Inline images
+
+`<img src="…" width=N height=N valign=baseline|middle|top|bottom offsetX=N
+offsetY=N scale=N tint=#RRGGBB />` (self-closing, `src` required) flows an image
+inline with the text. The same rich-text layout that places the glyphs places
+the image box — `valign` anchors it on the line, `width`/`height`/`scale` size
+it, `offsetX/Y` nudge it, `tint` recolors it — and it renders as a child image
+quad under the `Text`. `src` resolves through `Assets.loadTexture`, so it is a
+project-relative texture path.
+
+<Aside type="note">
+ Inline images render on **non-wrapped** rich text (give the `Text`
+ `wordWrap: false`); a wrapped rich `Text` lays out its text only and drops
+ image runs for now. Inline images also need the `Text` to have a `UINode`
+ box — they don't draw on a boxless world-space label.
</Aside>
## Measuring text
diff --git a/examples/rich-text/README.md b/examples/rich-text/README.md
index e211c6aa7..5293d029e 100644
--- a/examples/rich-text/README.md
+++ b/examples/rich-text/README.md
@@ -30,12 +30,14 @@ slots — `PreviewSlot`, `ComposerRow`, `ShowcaseSlot`. The startup `BuildSystem
The field text is plain (you see the literal `<b>…</b>` tags); the preview is
what those tags *mean*.
-## Note on `<img>`
-
-Inline images (`<img src="…" width=N height=N/>`) **parse** into an
-`ImageSegment` but the built-in text renderer does not draw them yet, so this
-demo leaves `<img>` out of the legend. Compose an icon next to text with flexbox
-instead. See the [Text guide](../../docs/astro/src/content/docs/guides/ui-text.mdx).
+## Inline images
+
+The last legend row flows an **icon inline with the text** —
+`HP <img src="assets/textures/heart.png" width=26 height=26 valign=middle/> 100`.
+`<img>` runs are placed by the same rich-text layout as the glyphs and drawn as
+child image quads (`valign` anchors them on the line; `width`/`height`/`scale`
+size them; `tint` recolors). Inline images render on **non-wrapped** rich text —
+wrapping is text-only for now, so give an image-bearing `Text` `wordWrap: false`.
## Run
diff --git a/examples/rich-text/assets/textures/heart.png b/examples/rich-text/assets/textures/heart.png
new file mode 100644
index 000000000..b5ca377ec
Binary files /dev/null and b/examples/rich-text/assets/textures/heart.png differ
diff --git a/examples/rich-text/assets/textures/heart.png.meta b/examples/rich-text/assets/textures/heart.png.meta
new file mode 100644
index 000000000..2a5a358ce
--- /dev/null
+++ b/examples/rich-text/assets/textures/heart.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "e4b1d7a2-8c50-4f39-a6b3-92e1c0f75a48",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "linear",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/rich-text/src/config.ts b/examples/rich-text/src/config.ts
index 400b168da..793f00eb1 100644
--- a/examples/rich-text/src/config.ts
+++ b/examples/rich-text/src/config.ts
@@ -4,11 +4,12 @@ export const SEED_MARKUP =
'Hello <b>世界</b> <color=#ffcc33>Estella</color> <i>rich text</i>!';
// The static reference panel: one line per supported tag, each rendered rich so
-// the demo doubles as a legend. `<img>` is intentionally left out — it parses
-// but the built-in renderer does not draw inline images yet (see README).
+// the demo doubles as a legend — including an inline `<img>` (an icon flowed in
+// with the text, valign-centered on the line).
export const SAMPLES: readonly string[] = [
'<b>bold</b> <i>italic</i> <b><i>bold italic</i></b>',
'<color=#ff5a5a>red</color> <color=#5aff8c>green</color> <color=#5a9cff>blue</color> <color=#ffd24a>gold</color>',
'font size <font size=14>14</font> <font size=22>22</font> <font size=32>32</font>',
'nested <color=#ffcc33>gold <b>bold</b> and <i>italic</i></color> back to plain',
+ 'inline image HP <img src="assets/textures/heart.png" width=26 height=26 valign=middle/> <color=#ff5a6e>100</color>',
];
diff --git a/examples/rich-text/src/systems/build.ts b/examples/rich-text/src/systems/build.ts
index 7d6a02595..8b075fa21 100644
--- a/examples/rich-text/src/systems/build.ts
+++ b/examples/rich-text/src/systems/build.ts
@@ -80,6 +80,9 @@ export const buildSystem = defineSystem(
content: line,
fontSize: 20,
richText: true,
+ // Single-line legend rows: no wrap so inline <img> runs render
+ // (wrapping is text-only for now).
+ wordWrap: false,
align: TextAlign.Left,
verticalAlign: TextVerticalAlign.Middle,
color: { r: 0.9, g: 0.9, b: 0.92, a: 1 },
diff --git a/sdk/src/ui/index.ts b/sdk/src/ui/index.ts
index 54fc93b20..5b3565a36 100644
--- a/sdk/src/ui/index.ts
+++ b/sdk/src/ui/index.ts
@@ -320,6 +320,7 @@ export { BUILTIN_UI_PREFABS, BUILTIN_UI_WIDGET_NAMES } from './widgets/prefabs/g
// All text — display (Text) and editable (TextInput) — now renders through the
// SDF glyph atlas; the Canvas2D TextRenderer was retired.
export { TextPlugin, textPlugin, resolveTextRenderMode } from './text/plugin';
+export { InlineImagePlugin, inlineImagePlugin } from './text/inline-image-plugin';
export { measureText, type MeasureTextOptions, type TextMetrics } from './text/measure-text';
// UI Math Utilities
@@ -484,6 +485,7 @@ export {
type RichTextLayoutOptions,
type MultilineTextOptions,
type LaidGlyph,
+ type LaidImage,
type RGBA,
type GlyphVertexData,
} from './text/layout';
diff --git a/sdk/src/ui/text/inline-image-plugin.ts b/sdk/src/ui/text/inline-image-plugin.ts
new file mode 100644
index 000000000..cc5465990
--- /dev/null
+++ b/sdk/src/ui/text/inline-image-plugin.ts
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ui/text/inline-image-plugin.ts
+ * @brief Renders inline `<img>` runs in rich `Text`. Additive to the SDF text
+ * pipeline: `TextPlugin` still draws only glyphs, and this plugin draws
+ * the images the SHARED rich layout (`layoutText` → `TextLayout.images`)
+ * places, as child `UIVisual` image quads under each rich Text that has
+ * them. Text WITHOUT `<img>` is never touched (the scan short-circuits
+ * on the marker), so the common path carries zero cost.
+ *
+ * Placement rides the same layout the glyphs do (one layout, no duplication),
+ * mapped from the glyph block's local space (baseline y-up) into child UINode
+ * insets: `insetLeft = image.x`, `insetTop = ascent + verticalAlignShift −
+ * image.y − image.h` (ascent ≈ fontSize × 0.8), matching where the glyph run
+ * flows the image. Textures resolve by `src` through `Assets.loadTexture`,
+ * cached; a child stays hidden until its texture lands.
+ */
+import type { App, Plugin } from '../../app';
+import { defineSystem, Schedule } from '../../system';
+import type { Entity } from '../../types';
+import type { ESEngineModule } from '../../wasm';
+import { Text, TextVerticalAlign, type TextData } from '../core/text';
+import { UINode, UIPositionType, type UINodeData } from '../core/ui-node';
+import { UIVisual, UIVisualType, type UIVisualData } from '../core/ui-visual';
+import { SdfTextRenderer } from './text-renderer';
+import { layoutText, type LaidImage } from './layout';
+import { rectTextBox, UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
+import { spawnUIEntity } from '../core/compose';
+import { px } from '../core/dimension';
+import { getUINodeWidth, getUINodeHeight } from '../util/helpers';
+import { Assets } from '../../asset/AssetPlugin';
+import type { Assets as AssetsApi } from '../../asset/Assets';
+
+const WHITE = { r: 1, g: 1, b: 1, a: 1 };
+
+export class InlineImagePlugin implements Plugin {
+ name = 'ui-inline-image';
+
+ private cleanup_: (() => void) | null = null;
+
+ cleanup(): void {
+ this.cleanup_?.();
+ this.cleanup_ = null;
+ }
+
+ build(app: App): void {
+ const module = app.wasmModule as ESEngineModule | undefined;
+ if (!module) return; // logic-only host → nothing to draw
+ const world = app.world;
+
+ // A measurement atlas for the shared layout — its glyph advances position
+ // the images after the text runs (see `layoutText`). SDF so metrics are
+ // resolution-independent; sub-pixel drift vs the draw atlas is invisible.
+ let measurer: SdfTextRenderer | null = null;
+ const atlas = () => (measurer ??= new SdfTextRenderer(module)).atlas;
+
+ const childrenOf = new Map<Entity, Entity[]>();
+ const textureOf = new Map<string, number>(); // src → handle (0 = failed)
+ const loading = new Set<string>();
+
+ /** Texture handle for `src`, kicking off an async load on first miss. */
+ const resolveTexture = (src: string): number | null => {
+ const h = textureOf.get(src);
+ if (h !== undefined) return h === 0 ? null : h;
+ if (!loading.has(src) && app.hasResource(Assets)) {
+ loading.add(src);
+ const assets = app.getResource(Assets) as AssetsApi;
+ assets.loadTexture(src)
+ .then((r) => textureOf.set(src, r.handle))
+ .catch(() => textureOf.set(src, 0));
+ }
+ return null;
+ };
+
+ const despawnKids = (kids: Entity[]): void => {
+ for (const k of kids) if (world.valid(k)) world.despawn(k);
+ };
+
+ app.addSystemToSchedule(Schedule.PreUpdate, defineSystem([], () => {
+ const seen = new Set<Entity>();
+
+ for (const e of world.getEntitiesWithComponents([Text, UINode])) {
+ const t = world.get(e, Text) as TextData;
+ // Short-circuit on the common case: plain / image-free text never
+ // lays out here, so it costs one substring scan and nothing more.
+ if (!t.richText || t.enabled === false || !t.content || !t.content.includes('<img')) continue;
+
+ const w = getUINodeWidth(e);
+ const h = getUINodeHeight(e);
+ if (w <= 0 || h <= 0) continue; // inline images need a laid-out box
+
+ const box = rectTextBox(0.5, 0.5, w, h, t.fontSize);
+ const style = (t.bold ? UI_TEXT_BOLD : 0) | (t.italic ? UI_TEXT_ITALIC : 0);
+ const layout = layoutText(t.content, atlas(), t.fontFamily, {
+ fontSizePx: t.fontSize,
+ lineHeight: t.lineHeight > 0 ? t.lineHeight * t.fontSize : undefined,
+ align: t.align,
+ rich: true,
+ color: [1, 1, 1, 1],
+ maxWidth: t.wordWrap ? box.maxWidth : undefined,
+ boxWidth: box.maxWidth,
+ }, style);
+
+ const images = layout.images ?? [];
+ if (images.length === 0) { reap(e); continue; }
+ seen.add(e);
+
+ // verticalAlign shifts the whole block down by the box slack — the
+ // same shift `drawTextWith` applies to the glyphs (mirror it so the
+ // images track the text).
+ const slack = h - layout.lineHeight;
+ const vshift = t.verticalAlign === TextVerticalAlign.Middle ? slack / 2
+ : t.verticalAlign === TextVerticalAlign.Bottom ? slack
+ : 0;
+ syncChildren(e, t, images, vshift);
+ }
+
+ // Reap children of text that lost its images / was despawned this frame.
+ for (const [e, kids] of childrenOf) {
+ if (!seen.has(e)) { despawnKids(kids); childrenOf.delete(e); }
+ }
+ }, { name: 'InlineImageSystem' }));
+
+ function reap(textEntity: Entity): void {
+ const kids = childrenOf.get(textEntity);
+ if (kids) { despawnKids(kids); childrenOf.delete(textEntity); }
+ }
+
+ function syncChildren(textEntity: Entity, t: TextData, images: LaidImage[], vshift: number): void {
+ let kids = childrenOf.get(textEntity);
+ if (!kids) { kids = []; childrenOf.set(textEntity, kids); }
+ while (kids.length < images.length) {
+ kids.push(spawnUIEntity({
+ world, parent: textEntity,
+ node: { position: UIPositionType.Absolute, insetLeft: px(0), insetTop: px(0), width: px(0), height: px(0) },
+ visual: { visualType: UIVisualType.Image, texture: 0, color: { ...WHITE }, enabled: false },
+ }));
+ }
+ while (kids.length > images.length) {
+ const k = kids.pop()!;
+ if (world.valid(k)) world.despawn(k);
+ }
+
+ const ascent = t.fontSize * 0.8;
+ for (let i = 0; i < images.length; i++) {
+ const im = images[i];
+ const tex = resolveTexture(im.src);
+ syncChild(kids[i], im.x, ascent + vshift - im.y - im.h, im.w, im.h, tex, im.tint);
+ }
+ }
+
+ function syncChild(
+ entity: Entity, left: number, top: number, width: number, height: number,
+ texture: number | null, tint: readonly [number, number, number, number] | null,
+ ): void {
+ const node = world.get(entity, UINode) as UINodeData;
+ if (node.insetLeft.value !== left || node.insetTop.value !== top
+ || node.width.value !== width || node.height.value !== height) {
+ node.insetLeft = px(left);
+ node.insetTop = px(top);
+ node.width = px(width);
+ node.height = px(height);
+ world.insert(entity, UINode, node);
+ }
+ const v = world.get(entity, UIVisual) as UIVisualData;
+ const on = texture !== null && texture !== 0;
+ const col = tint ? { r: tint[0], g: tint[1], b: tint[2], a: tint[3] } : WHITE;
+ if (v.enabled !== on || v.texture !== (texture ?? 0)
+ || v.color.r !== col.r || v.color.g !== col.g || v.color.b !== col.b || v.color.a !== col.a) {
+ v.enabled = on;
+ v.texture = texture ?? 0;
+ v.visualType = UIVisualType.Image;
+ v.color = { ...col };
+ world.insert(entity, UIVisual, v);
+ }
+ }
+
+ this.cleanup_ = () => {
+ for (const kids of childrenOf.values()) despawnKids(kids);
+ childrenOf.clear();
+ };
+ }
+}
+
+export const inlineImagePlugin = new InlineImagePlugin();
diff --git a/sdk/src/ui/text/layout.ts b/sdk/src/ui/text/layout.ts
index a1846b273..0cede459e 100644
--- a/sdk/src/ui/text/layout.ts
+++ b/sdk/src/ui/text/layout.ts
@@ -15,7 +15,7 @@
*/
import type { GlyphAtlas } from './glyph-atlas';
import { TEXT_VERTEX_FLOATS } from './submit';
-import { parseRichText, type TextSegment } from './rich-text-parser';
+import { parseRichText, type TextSegment, type ImageSegment, type RichTextRun } from './rich-text-parser';
import { UI_TEXT_BOLD, UI_TEXT_ITALIC } from './text-transform';
export interface TextLayoutOptions {
@@ -38,8 +38,22 @@ export interface LaidGlyph {
color?: RGBA;
}
+/** One placed inline `<img>` run: a box in the same local space as glyphs
+ * (y-up; (x,y) is the bottom-left corner). `src` is the image reference the
+ * renderer resolves to a texture; `tint` recolors it (null = untinted). */
+export interface LaidImage {
+ src: string;
+ x: number;
+ y: number;
+ w: number;
+ h: number;
+ tint: RGBA | null;
+}
+
export interface TextLayout {
glyphs: LaidGlyph[];
+ /** Inline `<img>` placements (rich text only). Undefined/empty = none. */
+ images?: LaidImage[];
/** Total pen advance (display px). */
width: number;
/** Line height (display px). */
@@ -246,12 +260,13 @@ export function layoutText(
const richOpts = { fontSizePx: opts.fontSizePx, letterSpacing: opts.letterSpacing, color: baseColor };
// Word-wrap before stacking; explicit \n still hard-breaks. Rich lines wrap
- // at the styled-run level so a token measures with its own size/style.
+ // at the styled-run level so a token measures with its own size/style. Inline
+ // images survive the no-wrap path; wrapping is text-only (images drop) for now.
const lineLayouts = opts.rich
? rawLines
- .map(l => parseRichText(l).filter((r): r is TextSegment => r.type === 'text'))
+ .map(l => parseRichText(l))
.flatMap(runs => (wrap
- ? wrapRichRuns(runs, atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
+ ? wrapRichRuns(runs.filter((r): r is TextSegment => r.type === 'text'), atlas, fontFamily, opts.fontSizePx, style, opts.maxWidth!, opts.letterSpacing ?? 0)
: [runs]))
.map(runs => layoutRichRuns(runs, atlas, fontFamily, richOpts, style))
: (wrap
@@ -267,6 +282,7 @@ export function layoutText(
: (opts.maxWidth && opts.maxWidth > 0) ? opts.maxWidth
: contentWidth;
const glyphs: LaidGlyph[] = [];
+ const images: LaidImage[] = [];
for (let i = 0; i < lineLayouts.length; i++) {
const ll = lineLayouts[i];
@@ -277,17 +293,20 @@ export function layoutText(
for (const g of ll.glyphs) {
glyphs.push({ ...g, x0: g.x0 + dx, x1: g.x1 + dx, y0: g.y0 + dy, y1: g.y1 + dy });
}
+ if (ll.images) {
+ for (const im of ll.images) images.push({ ...im, x: im.x + dx, y: im.y + dy });
+ }
}
- return { glyphs, width: contentWidth, lineHeight: lines.length * lineHeight };
+ return { glyphs, images, width: contentWidth, lineHeight: lines.length * lineHeight };
}
/**
- * Lay out a single line of rich text: `<b>`, `<i>`,
- * `<color=#rrggbb[aa]>`, `<font size=N>` runs (parsed by parseRichText) become
- * glyphs carrying per-run color + size + bold/italic style. Image runs (`<img>`)
- * are skipped for now. Each run scales by its own fontSize / atlas.renderSize;
- * all runs share the baseline (y = 0). Pure → unit-testable.
+ * Lay out a single line of rich text: `<b>`, `<i>`, `<color=#rrggbb[aa]>`,
+ * `<font size=N>` runs (parsed by parseRichText) become glyphs carrying per-run
+ * color + size + bold/italic style, and `<img>` runs become inline image boxes.
+ * Each run scales by its own fontSize / atlas.renderSize; all share the baseline
+ * (y = 0). Pure → unit-testable.
*/
export function layoutRichLine(
content: string,
@@ -296,9 +315,7 @@ export function layoutRichLine(
opts: RichTextLayoutOptions,
baseStyle = 0,
): TextLayout {
- return layoutRichRuns(
- parseRichText(content).filter((r): r is TextSegment => r.type === 'text'),
- atlas, fontFamily, opts, baseStyle);
+ return layoutRichRuns(parseRichText(content), atlas, fontFamily, opts, baseStyle);
}
/** Measure a styled run's advance width (mirrors layoutRichRuns' pen math). */
@@ -391,13 +408,37 @@ export function wrapRichRuns(
return lines.length ? lines : [[]];
}
+/** Place an `<img>` run's box on the pen. y-up local space, baseline at y = 0;
+ * `valign` picks the vertical anchor (ascent ≈ size×0.8, descent ≈ size×0.2),
+ * `offsetX/Y` nudge it, `scale` sizes it. The pen advances by the scaled width. */
+function placeImage(img: ImageSegment, penX: number, fontSizePx: number): LaidImage {
+ const w = img.width * img.scale;
+ const h = img.height * img.scale;
+ const ascent = fontSizePx * 0.8;
+ const descent = fontSizePx * 0.2;
+ let yBottom: number;
+ switch (img.valign) {
+ case 'top': yBottom = ascent - h; break;
+ case 'bottom': yBottom = -descent; break;
+ case 'middle': yBottom = (ascent - descent) / 2 - h / 2; break;
+ default: yBottom = 0; break; // baseline
+ }
+ return {
+ src: img.src,
+ x: penX + img.offsetX,
+ y: yBottom + img.offsetY,
+ w, h,
+ tint: img.tint ? [img.tint.r, img.tint.g, img.tint.b, img.tint.a] : null,
+ };
+}
+
/**
- * Lay out a single rich line from its styled runs: each run carries per-run
- * color + size + bold/italic; all runs share the baseline (y = 0). Image runs
- * never reach here (callers filter to TextSegments). Pure → unit-testable.
+ * Lay out a single rich line from its runs: text runs carry per-run color +
+ * size + bold/italic; `<img>` runs place an inline image box that advances the
+ * pen by its width. All share the baseline (y = 0). Pure → unit-testable.
*/
export function layoutRichRuns(
- runs: TextSegment[],
+ runs: RichTextRun[],
atlas: GlyphAtlas,
fontFamily: string,
opts: RichTextLayoutOptions,
@@ -405,10 +446,18 @@ export function layoutRichRuns(
): TextLayout {
const spacing = opts.letterSpacing ?? 0;
const glyphs: LaidGlyph[] = [];
+ const images: LaidImage[] = [];
let penX = 0;
let lineHeight = opts.fontSizePx;
for (const run of runs) {
+ if (run.type === 'image') {
+ const placed = placeImage(run, penX, opts.fontSizePx);
+ images.push(placed);
+ if (placed.h > lineHeight) lineHeight = placed.h;
+ penX += run.width * run.scale;
+ continue;
+ }
const runSize = run.fontSize ?? opts.fontSizePx;
const pixelSize = atlas.pixelSizeFor(runSize);
const scale = runSize / pixelSize;
@@ -436,5 +485,5 @@ export function layoutRichRuns(
}
}
- return { glyphs, width: penX, lineHeight };
+ return { glyphs, images, width: penX, lineHeight };
}
diff --git a/sdk/src/ui/ui-plugin.ts b/sdk/src/ui/ui-plugin.ts
index c0b635071..3cc84da01 100644
--- a/sdk/src/ui/ui-plugin.ts
+++ b/sdk/src/ui/ui-plugin.ts
@@ -20,6 +20,7 @@ import { uiLayoutPlugin } from './layout/layout';
import { uiMaskPlugin } from './render/mask';
import { safeAreaPlugin } from './layout/safe-area';
import { textPlugin } from './text/plugin';
+import { inlineImagePlugin } from './text/inline-image-plugin';
import { uiInteractionPlugin } from './input/interaction';
import { uiBehaviorPlugin } from './behavior/plugin';
import { uiControllerPlugin } from './controller/plugin';
@@ -40,6 +41,7 @@ const SUB_PLUGINS: Plugin[] = [
uiMaskPlugin,
safeAreaPlugin,
textPlugin,
+ inlineImagePlugin,
uiInteractionPlugin,
uiBehaviorPlugin,
uiControllerPlugin,
diff --git a/sdk/tests/ui-text-richlayout.test.ts b/sdk/tests/ui-text-richlayout.test.ts
index a0d1c6029..9ceda96e9 100644
--- a/sdk/tests/ui-text-richlayout.test.ts
+++ b/sdk/tests/ui-text-richlayout.test.ts
@@ -66,3 +66,54 @@ describe('REARCH_GUI P1.4: rich text layout', () => {
expect(vertices[6]).toBe(0); // b
});
});
+
+describe('rich text layout — inline images', () => {
+ it('places an <img> on the pen after the preceding text and advances by its width', () => {
+ const atlas = makeAtlas([]);
+ // Each glyph advances 11 * (24/48) = 5.5px; "AB" ⇒ pen at 11 before the image.
+ const layout = layoutRichLine(
+ 'AB<img src="heart" width=16 height=16/>C',
+ atlas, 'Arial', { fontSizePx: 24, color: [1, 1, 1, 1] });
+ expect(layout.images).toHaveLength(1);
+ const img = layout.images![0];
+ expect(img.src).toBe('heart');
+ expect(img.w).toBe(16);
+ expect(img.h).toBe(16);
+ expect(img.x).toBeCloseTo(11, 5);
+ expect(img.y).toBeCloseTo(0, 5); // baseline valign ⇒ bottom on the baseline
+ // The trailing "C" glyph starts after the 16px image (pen = 11 + 16 = 27).
+ expect(layout.glyphs[layout.glyphs.length - 1].x0).toBeGreaterThan(27 - 1);
+ });
+
+ it('scales the box and applies tint + offset', () => {
+ const atlas = makeAtlas([]);
+ const layout = layoutRichLine(
+ '<img src="coin" width=10 height=10 scale=2 offsetX=3 offsetY=-4 tint=#ff8000/>',
+ atlas, 'Arial', { fontSizePx: 24, color: [1, 1, 1, 1] });
+ const img = layout.images![0];
+ expect(img.w).toBe(20);
+ expect(img.h).toBe(20);
+ expect(img.x).toBeCloseTo(3, 5); // penX 0 + offsetX 3
+ expect(img.y).toBeCloseTo(-4, 5); // baseline 0 + offsetY -4
+ expect(img.tint).not.toBeNull();
+ expect(img.tint![0]).toBeCloseTo(1, 2); // r = ff
+ expect(img.tint![2]).toBeCloseTo(0, 2); // b = 00
+ });
+
+ it('valign top/baseline/bottom order the box vertically', () => {
+ const atlas = makeAtlas([]);
+ const mk = (v: string) => layoutRichLine(`<img src="x" width=16 height=16${v}/>`, atlas, 'Arial', { fontSizePx: 24, color: [1, 1, 1, 1] }).images![0].y;
+ const top = mk(' valign=top');
+ const base = mk(''); // baseline: bottom on y = 0
+ const bottom = mk(' valign=bottom');
+ expect(base).toBeCloseTo(0, 5);
+ expect(top).toBeGreaterThan(base); // y-up: top anchor raises the box
+ expect(bottom).toBeLessThan(base); // bottom anchor drops it below the baseline
+ });
+
+ it('plain rich text yields an empty images array', () => {
+ const atlas = makeAtlas([]);
+ const layout = layoutRichLine('<b>hi</b>', atlas, 'Arial', { fontSizePx: 24, color: [1, 1, 1, 1] });
+ expect(layout.images).toEqual([]);
+ });
+});