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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 & AudioTrackPrchildren?: 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.tsindex 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.tsindex 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.mdindex 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.tsindex 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.mdindex 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.mdindex 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. |