Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance text handling with new TextCase and TextRange features

konstantin-paulus9206d58d85a1
diff --git a/packages/jsx/src/index.ts b/packages/jsx/src/index.ts
index 21a0fa17..b0190e0e 100644
--- a/packages/jsx/src/index.ts
+++ b/packages/jsx/src/index.ts
@@ -71,7 +71,9 @@ export type {
SurfaceHandle,
SurfacePaintProps,
SurfaceProps,
+ TextCase,
TextProps,
+ TextRangeProps,
Time,
TransitionSpec,
TransitionType,
diff --git a/packages/jsx/src/jsx-runtime.ts b/packages/jsx/src/jsx-runtime.ts
index eae4ebac..864ef984 100644
--- a/packages/jsx/src/jsx-runtime.ts
+++ b/packages/jsx/src/jsx-runtime.ts
@@ -45,6 +45,7 @@ import type {
SurfacePaintProps,
SurfaceProps,
TextProps,
+ TextRangeProps,
VideoProps,
} from "./types";
@@ -82,6 +83,7 @@ export declare namespace JSX {
image: (ImageProps & SourceProps) | SolidJSX.SVGElementTags["image"];
audio: AudioProps & SourceProps;
text: (TextProps & SourceProps) | SolidJSX.SVGElementTags["text"];
+ textRange: TextRangeProps & SourceProps;
sequence: SequenceProps & SourceProps;
captions: CaptionsProps & SourceProps;
solidPaint: SolidPaintProps & SourceProps;
diff --git a/packages/jsx/src/source.ts b/packages/jsx/src/source.ts
index 9708c928..3cec9346 100644
--- a/packages/jsx/src/source.ts
+++ b/packages/jsx/src/source.ts
@@ -97,6 +97,7 @@ export const COMPOSITION_TAGS = [
"image",
"audio",
"text",
+ "textRange",
"sequence",
"captions",
"solidPaint",
diff --git a/packages/jsx/src/types.ts b/packages/jsx/src/types.ts
index b4f46983..4b711332 100644
--- a/packages/jsx/src/types.ts
+++ b/packages/jsx/src/types.ts
@@ -138,6 +138,9 @@ export type AnimationType =
| "appearChar"
| "scramble";
+/** How glyphs are cased when drawn, whatever the text says. Default "original". */
+export type TextCase = "original" | "upper" | "lower";
+
/** Caption style presets — the editor's caption inspector presets. */
export type CaptionPreset =
| "classic"
@@ -285,6 +288,26 @@ type ColorProps = {
color: string;
};
+/**
+ * How glyphs are set: the style a `<text>` gives all its glyphs, and a
+ * `<textRange>` gives the glyphs it spans. Every field is optional on both; on
+ * a range an unset field inherits the text's, so a range says only what it
+ * changes.
+ */
+type FontProps = {
+ /** A family available on the machine (`dapi fonts`). */
+ fontFamily?: string;
+ /** Font size, px. */
+ fontSize?: number;
+ /** CSS weights 100–900, or "normal" / "bold". */
+ fontWeight?: number | "normal" | "bold";
+ fontStyle?: "normal" | "italic" | "oblique";
+ /** Extra space between glyphs, px (negative tightens). Default 0. */
+ letterSpacing?: number;
+ /** Casing applied when drawing; the text itself is left as written. Default "original". */
+ textCase?: TextCase;
+};
+
/** What every visual node accepts on top of its own props. */
type CommonProps = IdentityProps & TransformProps & CompositeProps & TimingProps & SequenceItemProps;
@@ -538,24 +561,42 @@ export type AudioProps = IdentityProps & TimingProps & MediaProps & AudioTrackPr
children?: SolidJSX.Element;
};
-export type TextProps = CommonProps & Partial<ColorProps> & {
- /** A family available on the machine (`dapi fonts`). */
- fontFamily?: string;
- /** Font size, px. */
- fontSize?: number;
- /** CSS weights 100–900, or "normal" / "bold". */
- fontWeight?: number | "normal" | "bold";
- fontStyle?: "normal" | "italic";
+export type TextProps = CommonProps & Partial<ColorProps> & FontProps & {
/** Horizontal alignment of glyphs within the box. Default "left". */
textAlign?: "left" | "center" | "right";
- /** Vertical alignment within the box. Default "top". */
- textBaseline?: "top" | "middle" | "bottom";
- /**
- * The text content, required; alongside it, paint, `<Stroke>`, `<Shadow>`,
- * `<Effect>`, `<Animation>` and `<KeyframeTrack>` children.
- */
- children: SolidJSX.Element;
- };
+ /**
+ * Vertical alignment within the box: the block anchored to the top or
+ * bottom of the box or centered, or ("alphabetic") the first line's baseline
+ * at the top of the box. Default "top".
+ */
+ textBaseline?: "top" | "middle" | "bottom" | "alphabetic";
+ /** Line height as a multiple of each line's natural height. Default 1. */
+ leading?: number;
+ /**
+ * The text content, required; alongside it, `<TextRange>`, paint,
+ * `<Stroke>`, `<Shadow>`, `<Effect>`, `<Animation>` and `<KeyframeTrack>`
+ * children.
+ */
+ children: SolidJSX.Element;
+};
+
+/**
+ * `<textRange>` — a style override for a run of the parent `<text>`'s glyphs,
+ * a sub-entity like a paint: `start`/`end` address the run by character index
+ * into the text as written (before `textCase`), the rest is what changes
+ * inside it. Its own `color`, paints, strokes and shadows replace the text's
+ * for those glyphs; an unset font field inherits. Several stack in document
+ * order, later ones winning where they overlap; layout stays the text's
+ * (`textAlign`, `textBaseline`, `leading` are not per range).
+ */
+export type TextRangeProps = Partial<ColorProps> & FontProps & {
+ /** First character of the run, 0-based. */
+ start: number;
+ /** One past the last character of the run. Defaults to the end of the text. */
+ end?: number;
+ /** Paint, `<Stroke>`, `<Shadow>` and `<KeyframeTrack>` (a `color` track) children. */
+ children?: SolidJSX.Element;
+};
export type SequenceProps = Pick<IdentityProps, "name"> & {
children?: SolidJSX.Element;
diff --git a/packages/reconciler/src/document.ts b/packages/reconciler/src/document.ts
index 7095c485..e603022a 100644
--- a/packages/reconciler/src/document.ts
+++ b/packages/reconciler/src/document.ts
@@ -79,6 +79,8 @@ import {
SurfaceHostHandle,
TextAlign,
TextBaseline,
+ TextCase,
+ TextRange,
TextStyle,
Transition,
TransitionType,
@@ -366,6 +368,13 @@ const TEXT_BASELINES: Record<string, TextBaseline> = {
top: TextBaseline.TOP,
middle: TextBaseline.MIDDLE,
bottom: TextBaseline.BOTTOM,
+ alphabetic: TextBaseline.ALPHABETIC,
+};
+
+const TEXT_CASES: Record<string, TextCase> = {
+ original: TextCase.ORIGINAL,
+ upper: TextCase.UPPER,
+ lower: TextCase.LOWER,
};
const FONT_WEIGHTS: Record<string, string> = {
@@ -481,6 +490,13 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
entity.add(TextStyle);
break;
}
+ case 'textRange': {
+ entity = createEntity(this.world);
+ entity.add(TextRange);
+ entity.set(TextRange, { start: 0, end: null });
+ entity.add(TextStyle);
+ break;
+ }
case 'video': {
entity = createEntity(this.world);
entity.add(Geometry);
@@ -590,7 +606,7 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
}
default:
throw new Error(
- `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <rect>, <text>, <video>, <image>, <audio>, <surface>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <shaderPaint>, <surfacePaint>, <colorStop>, <stroke>, <shadow>, <effect>, <animation>, <keyframeTrack> and <keyframe>).`,
+ `<${tag}> is not supported yet (only <stage>, <scene>, <group>, <sequence>, <rect>, <text>, <textRange>, <video>, <image>, <audio>, <surface>, <solidPaint>, <linearGradientPaint>, <radialGradientPaint>, <shaderPaint>, <surfacePaint>, <colorStop>, <stroke>, <shadow>, <effect>, <animation>, <keyframeTrack> and <keyframe>).`,
);
}
@@ -899,6 +915,19 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
case 'end':
case 'sourceIn':
case 'sourceOut': {
+ if (entity.has(TextRange)) {
+ // A range's start/end are character indices, not times; an
+ // unset end runs to the end of the text.
+ if (name === 'start') {
+ entity.set(TextRange, { start: Math.max(0, Math.trunc(toNumber(value) ?? 0)) });
+ }
+ if (name === 'end') {
+ const end = toNumber(value);
+ entity.set(TextRange, { end: end === undefined ? null : Math.max(0, Math.trunc(end)) });
+ }
+ return;
+ }
+
const trait = TIME_TRAITS[name];
const seconds = toSeconds(value);
@@ -1017,6 +1046,22 @@ export class RuntimeDocument implements ProjectDocument<HostNode> {
entity.set(TextStyle, { textBaseline: typeof value === 'string' ? TEXT_BASELINES[value] : undefined });
return;
}
+ case 'textCase': {
+ entity.add(TextStyle);
+ entity.set(TextStyle, { textCase: typeof value === 'string' ? TEXT_CASES[value] : undefined });
+ return;
+ }
+ case 'letterSpacing': {
+ entity.add(TextStyle);
+ entity.set(TextStyle, { letterSpacing: toNumber(value) });
+ return;
+ }
+ case 'leading': {
+ const leading = toNumber(value);
+ entity.add(TextStyle);
+ entity.set(TextStyle, { leading: leading !== undefined && leading > 0 ? leading : undefined });
+ return;
+ }
case 'background': {
const color = parseColor(value);
this.stage.entity.set(Background, { value: color ?? DEFAULT_BACKGROUND });
diff --git a/packages/reconciler/src/elements.ts b/packages/reconciler/src/elements.ts
index e06bf983..34f56280 100644
--- a/packages/reconciler/src/elements.ts
+++ b/packages/reconciler/src/elements.ts
@@ -41,6 +41,7 @@ import type {
SurfacePaintProps,
SurfaceProps,
TextProps,
+ TextRangeProps,
VideoProps,
} from "@diffusionstudio/jsx";
@@ -88,6 +89,7 @@ export const Video = hostElement<VideoProps>("Video");
export const Image = hostElement<ImageProps>("Image");
export const Audio = hostElement<AudioProps>("Audio");
export const Text = hostElement<TextProps>("Text");
+export const TextRange = hostElement<TextRangeProps>("TextRange");
export const Sequence = hostElement<SequenceProps>("Sequence");
export const Captions = hostElement<CaptionsProps>("Captions");
export const SolidPaint = hostElement<SolidPaintProps>("SolidPaint");
diff --git a/packages/runtime/MIGRATION.md b/packages/runtime/MIGRATION.md
index 0f633226..c3d3cb8a 100644
--- a/packages/runtime/MIGRATION.md
+++ b/packages/runtime/MIGRATION.md
@@ -157,6 +157,8 @@ apps/web now depends on `@diffusionstudio/runtime` and `@diffusionstudio/koota-s
**Static props the runtime already played but the host dropped, plus `<shaderPaint>`/`<surfacePaint>`/`<surface>`.** `cornerRadius` (`CornerRadius`; the `vertexRadius` keyframe path was already mapped, so a keyframed radius worked while a static one was ignored), `transition` on sequence items (`Transition` on the outgoing clip: `{}` is dissolve/1s, a partial value merges, `null`/unset removes; playback still drops it when the parent is not `Sequential`), and four new props: `scale` (`UniformScale`, wins over per-axis while present, as the motion system already resolves it), `scaleX`/`scaleY` (`Scale`), `blendMode` (`BlendMode`, camelCase composite operations, `sourceOver` removes the trait), `hidden` (`Hidden`), `playbackRate` (`PlaybackRate`, 0/unset removes). `scale`/`scaleX`/`scaleY` joined `AnimatableProperty` (motion paths `scale`/`scale.x`/`scale.y` existed). Types: `CompositeProps` (`blendMode`, `hidden`) is in `CommonProps` and in the new `PaintProps` (`OpacityProps` + composite) that all paints and `<stroke>` use; `<shadow>` takes `hidden` only. `<shaderPaint>` is `Paint(SHADER)` + `Shader` (`wgsl` -> `code`, `uniforms` copied); the host resolves lazily from `Shader.code` as before. `<surfacePaint>` is `Paint(SURFACE)`; `<surface>` a rect with an intrinsic (unauthored) surface paint child. Refs are plain Solid refs everywhere: `RuntimeDocument` implements no `applyRef`, so the renderer's `use` falls through to Solid's default and both forms (`ref={fn}`, `ref={variable}`) receive the `HostNode` synchronously. `<surface>` is a rect whose surface is its intrinsic paint, like `<video>`'s media (`Paint(SURFACE)` + `SurfaceHostHandle` on the geometry itself, no child paint; `renderIntrinsicFill` gained the SURFACE branch), `<surfacePaint>` the sub-entity form. Both nodes are `SurfaceNode` (`{ entity, canvas }`, `canvas` a getter over the entity's `SurfaceHostHandle`, typed for authors as `SurfaceHandle` in `@diffusionstudio/jsx`); the `SurfaceHost` is allocated with the element (`attachSurfaceHost`, skipped without a DOM) and sized by `syncSurfaceSize` when a paint meets its holder and whenever the holder's `width`/`height` props are set. `SurfaceHost.setSize` became a no-op for an unchanged size, since assigning a canvas dimension clears the bitmap even at the same value and user code (three.js `setSize`) may already have applied it. Because Solid applies refs before props on the spread path, the canvas seen *inside* the ref callback is not yet box-sized; it is by the time the render returns, and drawing happens in tickers/effects anyway. An earlier draft deferred a canvas-valued ref through `onMount`; dropped for the uniform, synchronous behaviour. A duplicated `<surface>` is a static empty one (its ref is not a `PropValue`), matching the old docs.
+ **Text is fully hosted: the remaining `TextStyle` fields and `<textRange>`.** `TextProps` gained `letterSpacing` (px, `TextStyle.letterSpacing`), `textCase` (`original`/`upper`/`lower`, the new `TextCase` type in `@diffusionstudio/jsx`, mapped onto the runtime enum; the glyphs are cased when drawn, `Chars` stays as written), `leading` (line height as a multiple of the natural line height, `TextStyle.leading`; non-positive/unset removes it), `textBaseline="alphabetic"` (`TextBaseline.ALPHABETIC`, which `shapeTokens` already laid out) and `fontStyle="oblique"` (was mapped, not typed). The font fields (`fontFamily`/`fontSize`/`fontWeight`/`fontStyle`/`letterSpacing`/`textCase`) moved into a shared `FontProps` group because `<textRange>` takes the same ones. `<textRange start end>` (`TextRangeProps`, `textRange` in `IntrinsicElements` and `COMPOSITION_TAGS`, `TextRange` component in the reconciler) is the element form of the runtime's `TextRange` sub-entity — a style override over a run of the parent `<text>`'s glyphs, addressed by character index into the text as written (`end` unset is `null`, to the end), stacking in document order with later ones winning where they overlap, exactly what the caption presets build by hand. Its recipe is `TextRange` + a sparse `TextStyle` (an unset field inherits the text's, which is how `utils/text.ts`'s per-range accessors already read it), plus `Color` when `color` is set, and it takes paint, `<stroke>`, `<shadow>` and `<keyframeTrack>` (a `color` track) children, whose caches `rebuildCaches` already builds per parent. `setProperty('start'|'end')` branches on `TextRange` first, since on every other element those names are timing props. One runtime change: `renderTokens` resolved the intrinsic glyph fill once per text (`entity.has(Color)`), so a range could recolor glyphs only through a solid paint child; it now resolves it per word through `getIntrinsicColor`, the last range in the word's ranges carrying `Color` winning over the text's (via `Computed.color`, so a keyframed range color animates), which is what makes `<textRange color>` a plain prop. Layout props (`textAlign`, `textBaseline`, `leading`) stay per text: the shaper reads them from the node only. Not exposed: the motion system's `chars` keyframe path (a `Keyframe.value` is a number, so nothing meaningful can be authored on it) and `Opacity` on a range (nothing reads it; a range's translucency is its paints').
+
**Left stale on purpose** (deferred to a docs/examples pass): all eight `examples/*.tsx` still open with `<rect scene="...">` and no `<stage>`, so `tsc -p examples --noEmit` fails on them; `reference/jsx/{scene,roots}.md` still describes the pre-`<stage>` model where a mount grafts roots into an existing document; and `reference/jsx/{audio-sync,video,audio,elements}.md` still document `key` as the `syncTo` target. Deliberately not half-migrated: `reference/jsx` is stale as a whole, and patching the `key` rows alone would hide that.
## Remaining work (suggested order)
diff --git a/packages/runtime/src/utils/text.ts b/packages/runtime/src/utils/text.ts
index d14dbddd..93077832 100644
--- a/packages/runtime/src/utils/text.ts
+++ b/packages/runtime/src/utils/text.ts
@@ -382,20 +382,19 @@ function renderTokens(ctx: Ctx, world: World, entity: Entity): void {
ctx.textAlign = 'start';
ctx.textBaseline = 'top';
- // The geometry's own Color is an intrinsic solid fill beneath every paint.
- const hasIntrinsicFill = entity.has(Color);
- const intrinsicFill = hasIntrinsicFill ? colorToHex(computed.color[eid] ?? 0) : '';
-
for (const word of words) {
+ // The geometry's own Color is an intrinsic solid fill beneath every
+ // paint; a range carrying a Color replaces it over the glyphs it spans.
+ const intrinsicFill = getIntrinsicColor(world, entity, word.ranges);
const fills = getFills(world, entity, word.ranges);
- if (!fills.length && !hasIntrinsicFill) continue;
+ if (!fills.length && intrinsicFill === null) continue;
applyFont(ctx, world, entity, word.ranges);
const w = computed.width[eid]!;
const h = computed.height[eid]!;
- if (hasIntrinsicFill) {
+ if (intrinsicFill !== null) {
ctx.globalAlpha = savedAlpha;
ctx.fillStyle = intrinsicFill;
ctx.fillText(word.chars, word.x, word.y);
@@ -547,6 +546,23 @@ export function transformText(text: string, textCase?: number): string {
return text;
}
+/**
+ * The intrinsic glyph color for a run: the last of `ranges` carrying a Color
+ * wins over the text's own, as a hex string; null when neither has one.
+ */
+function getIntrinsicColor(world: World, entity: Entity, ranges: Entity[]): string | null {
+ const computed = store(world, Computed);
+ let value: number | undefined = entity.has(Color) ? computed.color[entity.id()] ?? 0 : undefined;
+
+ for (const range of ranges) {
+ if (range.has(Color)) {
+ value = computed.color[range.id()] ?? store(world, Color).value[range.id()] ?? 0;
+ }
+ }
+
+ return value === undefined ? null : colorToHex(value);
+}
+
function getFills(world: World, entity: Entity, ranges: Entity[]): Entity[] {
const cache = store(world, Cache);
let value = cache.fills[entity.id()] ?? [];
diff --git a/reference/jsx/elements.md b/reference/jsx/elements.md
index a32bf4ab..86ea944f 100644
--- a/reference/jsx/elements.md
+++ b/reference/jsx/elements.md
@@ -10,6 +10,7 @@ camelCase composition elements map 1:1 onto internal node types. Lowercase DOM v
| [`<image>`](./image.md) | **Geometry with Image paint** | `src` resolves to an image asset. |
| [`<audio>`](./audio.md) | **Geometry with Audio component and a hidden Waveform paint** | No visual output; carries volume. |
| [`<text>`](./text.md) | **Geometry with Text component** | Children become editable glyphs. |
+| [`<textRange>`](./text.md#textrange) | **Text range sub-entity** | Style override over a run of the parent `<text>`'s glyphs, by character index. |
| [`<sequence>`](./sequences.md) | **Sequential group** | Track container for back-to-back clips; positions are explicit. |
| [`<captions>`](./captions.md) | **Caption node** | Transcribes the enclosing scene's audio. |
| [`<solidPaint>`](./paints.md) | **Solid paint** | Paint child. |
diff --git a/reference/jsx/text.md b/reference/jsx/text.md
index a75e6db5..a5931db9 100644
--- a/reference/jsx/text.md
+++ b/reference/jsx/text.md
@@ -3,7 +3,7 @@
A text node; children become editable glyphs. Because the box defaults to the parent's box, a centered full-frame title is simply `<text textAlign="center" textBaseline="middle">…</text>`.
```tsx
-<text fill="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">
+<text color="#FFFFFF" fontSize={128} fontWeight="bold" textAlign="center" textBaseline="middle">
Hello World
</text>
```
@@ -14,13 +14,38 @@ All [common props](./elements.md#common-props), plus:
| Prop | Type | Default | Meaning |
| ---- | ---- | ------- | ------- |
-| children | `string` (or expressions resolving to strings) | **required** | The text content. |
+| children | `string` (or expressions resolving to strings) | **required** | The text content, alongside any `<textRange>`, paint, `<stroke>`, `<shadow>`, `<effect>`, `<animation>` and `<keyframeTrack>` children. |
+| `color` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Drawn beneath any paint children (see [paints.md](./paints.md)); animate it with a `color` [keyframe track](./keyframes.md). |
| `fontFamily` | `string` | editor default | A family available on the machine ([`dapi fonts`](../fonts.md)); see [fonts.md](./fonts.md). |
| `fontSize` | `number` | editor default | Px. |
| `fontWeight` | `number \| "normal" \| "bold"` | `"normal"` | CSS weights `100`-`900`. |
-| `fontStyle` | `"normal" \| "italic"` | `"normal"` | |
-| `fill` | `string` | white | The glyph color; any CSS color, alpha ignored (use `opacity`). Shorthand for a solid paint child (see [paints.md](./paints.md)); animate it by declaring the paint explicitly. |
+| `fontStyle` | `"normal" \| "italic" \| "oblique"` | `"normal"` | |
+| `letterSpacing` | `number` | `0` | Extra space between glyphs, px; negative tightens. |
+| `textCase` | `"original" \| "upper" \| "lower"` | `"original"` | Casing applied when drawing; the text itself stays as written. |
| `textAlign` | `"left" \| "center" \| "right"` | `"left"` | Horizontal alignment of glyphs within the box. |
-| `textBaseline` | `"top" \| "middle" \| "bottom"` | `"top"` | Vertical alignment within the box. |
+| `textBaseline` | `"top" \| "middle" \| "bottom" \| "alphabetic"` | `"top"` | Vertical alignment within the box: the block anchored to the top or bottom, centered, or (`"alphabetic"`) the first line's baseline at the top of the box. |
+| `leading` | `number` | `1` | Line height as a multiple of each line's natural height. |
The text-only [animation types](./animations.md) (`"appearWord"`, `"appearChar"`, `"scramble"`) animate the glyphs themselves.
+
+## `<textRange>`
+
+A style override for a run of the glyphs, a sub-entity like a paint: `start`/`end` address the run by character index into the text as written (before `textCase`), and the rest is what changes inside it. An unset font prop inherits the text's; its own `color`, paints, strokes and shadows replace the text's for those glyphs. Several stack in document order, later ones winning where they overlap. Layout (`textAlign`, `textBaseline`, `leading`) stays the text's.
+
+```tsx
+<text fontSize={96} color="#FFFFFF" textAlign="center" textBaseline="middle">
+ Ship it today
+ <textRange start={5} end={7} color="#F43F5E" fontWeight="bold" />
+ <textRange start={8} fontStyle="italic" letterSpacing={2}>
+ <stroke color="#000000" width={2} />
+ </textRange>
+</text>
+```
+
+| Prop | Type | Default | Meaning |
+| ---- | ---- | ------- | ------- |
+| `start` | `number` | **required** | First character of the run, 0-based. |
+| `end` | `number` | end of text | One past the last character of the run. |
+| `color` | `string` | inherits | The run's glyph color; any CSS color. |
+| `fontFamily`, `fontSize`, `fontWeight`, `fontStyle`, `letterSpacing`, `textCase` | as on `<text>` | inherit | Font overrides for the run. |
+| children | | | Paint, `<stroke>`, `<shadow>` and `<keyframeTrack>` (a `color` track) children. |