Merge pull request #19 from tinygodsdev/feat/vertical-writing-api

Expose vertical writing through the API, MCP, and the agent skill (BLD-137)

Author: dani-polani

bitext/src/lib/api/align.test.ts

@@ -282,3 +282,74 @@ describe('buildAlignUrl', () => {
 		expect(buildAlignUrl(ORIGIN, { lines })).not.toHaveProperty('err');
 	});
 });
+
+// ── Vertical writing ──────────────────────────────────────────────────────────
+
+describe('vertical writing', () => {
+	it('accepts the column axis and per-line orientation', () => {
+		const parsed = parseAlignBody({
+			lines: [
+				'The cat ate the fish',
+				{ text: '猫 が 魚 を 食べた', orientation: 'vertical', font: 'Noto Serif JP' }
+			],
+			settings: { axis: 'columns' }
+		});
+		if ('err' in parsed) throw new Error(parsed.err);
+		expect(parsed.ok.settings?.axis).toBe('columns');
+		expect(parsed.ok.lines[1]).toMatchObject({ orientation: 'vertical' });
+	});
+
+	it('encodes the axis into the shared state, not as a stray key', () => {
+		const result = buildAlignUrl(ORIGIN, {
+			lines: ['one two', { text: '猫 魚', orientation: 'vertical' }],
+			settings: { axis: 'columns' }
+		});
+		if (!('url' in result)) throw new Error(result.err);
+		const state = decodeState(new URL(result.url).searchParams.get('data'));
+		expect(state.settings.layoutAxis).toBe('columns');
+		expect(state.project.lines[1]!.textOrientation).toBe('vertical');
+		expect(state.project.lines[0]!.textOrientation).toBeUndefined();
+	});
+
+	it('carries the sideways orientation for Mongolian', () => {
+		const result = buildAlignUrl(ORIGIN, {
+			lines: [
+				{ text: 'ᠮᠣᠩᠭᠣᠯ ᠪᠢᠴᠢᠭ', orientation: 'sideways', font: 'Noto Sans Mongolian' },
+				'Mongolian script'
+			],
+			settings: { axis: 'columns' }
+		});
+		if (!('url' in result)) throw new Error(result.err);
+		const state = decodeState(new URL(result.url).searchParams.get('data'));
+		expect(state.project.lines[0]!.textOrientation).toBe('sideways');
+	});
+
+	it('defaults to rows and upright when neither is given', () => {
+		const result = buildAlignUrl(ORIGIN, { lines: ['a b', 'c d'] });
+		if (!('url' in result)) throw new Error(result.err);
+		const state = decodeState(new URL(result.url).searchParams.get('data'));
+		expect(state.settings.layoutAxis).toBe('rows');
+		expect(state.project.lines[0]!.textOrientation).toBeUndefined();
+	});
+
+	it('treats an explicit upright orientation as the default', () => {
+		const result = buildAlignUrl(ORIGIN, {
+			lines: [{ text: 'a b', orientation: 'upright' }, 'c d']
+		});
+		if (!('url' in result)) throw new Error(result.err);
+		const state = decodeState(new URL(result.url).searchParams.get('data'));
+		expect(state.project.lines[0]!.textOrientation).toBeUndefined();
+	});
+
+	it('rejects an unknown axis', () => {
+		expect(parseAlignBody({ lines: ['a'], settings: { axis: 'diagonal' } })).toMatchObject({
+			err: expect.stringContaining('settings.axis')
+		});
+	});
+
+	it('rejects an unknown orientation', () => {
+		expect(parseAlignBody({ lines: [{ text: 'a', orientation: 'upside-down' }] })).toMatchObject({
+			err: expect.stringContaining('orientation')
+		});
+	});
+});

bitext/src/lib/api/align.ts

@@ -15,6 +15,10 @@ import {
 	type VisualSettingsV2
 } from '$lib/serialization/schema.js';
 import { PALETTES } from '$lib/domain/palettes.js';
+import type { LayoutAxis, TextOrientation } from '$lib/types/layout.js';
+
+const TEXT_ORIENTATIONS = ['upright', 'vertical', 'sideways'] as const;
+const LAYOUT_AXES = ['rows', 'columns'] as const;
 
 const DEFAULT_FONT_FAMILY = 'Inter';
 const DEFAULT_TEXT_SIZE_PX = 36;
@@ -32,12 +36,26 @@ export interface LineInput {
 	sizePx?: number;
 	/** Horizontal gap between word tokens in px (0–56). Defaults to 14. */
 	gapPx?: number;
-	/** Right-to-left layout (Hebrew, Arabic, etc.). Defaults to false. */
+	/** Right-to-left layout (Hebrew, Arabic, etc.). Defaults to false. Ignored when orientation is "vertical". */
 	rtl?: boolean;
+	/**
+	 * How this line's glyphs are set. Defaults to "upright" (words render horizontally).
+	 * "vertical" stacks the characters, for Japanese and Chinese. "sideways" rotates the whole
+	 * line a quarter turn, which is what traditional Mongolian needs and what a Latin line inside
+	 * vertical text usually wants. Only visible with `settings.axis: "columns"`.
+	 */
+	orientation?: TextOrientation;
 }
 
 /** Global visual settings overrides. All fields optional; unset fields inherit defaults. */
 export interface SettingsInput {
+	/**
+	 * Flow direction of the whole diagram. Defaults to "rows": lines stack downward, words run
+	 * across, connectors run vertically. "columns" stands every line up as a vertical column with
+	 * connectors running sideways, for Japanese, Chinese, and Mongolian. The first line is
+	 * leftmost, so reorder `lines` to put a script on the other side.
+	 */
+	axis?: LayoutAxis;
 	/** Color palette for connection lines. */
 	palette?: 'pastel' | 'vivid';
 	/** Connection line shape. */
@@ -113,12 +131,15 @@ function parseLineEntry(val: unknown, idx: number): LineInput | { err: string }
 		return { err: `lines[${idx}].gapPx must be a number` };
 	if (v.rtl !== undefined && typeof v.rtl !== 'boolean')
 		return { err: `lines[${idx}].rtl must be a boolean` };
+	if (v.orientation !== undefined && !TEXT_ORIENTATIONS.includes(v.orientation as TextOrientation))
+		return { err: `lines[${idx}].orientation must be one of: ${TEXT_ORIENTATIONS.join(', ')}` };
 	return {
 		text: v.text,
 		font: typeof v.font === 'string' ? v.font : undefined,
 		sizePx: typeof v.sizePx === 'number' ? v.sizePx : undefined,
 		gapPx: typeof v.gapPx === 'number' ? v.gapPx : undefined,
-		rtl: typeof v.rtl === 'boolean' ? v.rtl : undefined
+		rtl: typeof v.rtl === 'boolean' ? v.rtl : undefined,
+		orientation: v.orientation as TextOrientation | undefined
 	};
 }
 
@@ -130,6 +151,8 @@ function parseSettingsInput(val: unknown): { ok: SettingsInput } | { err: string
 	const STYLES = new Set(['straight', 'curved']);
 	const THEMES_AND_BKGS = new Set(['light', 'dark']);
 
+	if (v.axis !== undefined && !LAYOUT_AXES.includes(v.axis as LayoutAxis))
+		return { err: `settings.axis must be one of: ${LAYOUT_AXES.join(', ')}` };
 	if (v.palette !== undefined && !PALETTE_NAMES.has(v.palette as string))
 		return { err: `settings.palette must be one of: ${[...PALETTE_NAMES].join(', ')}` };
 	if (v.lineStyle !== undefined && !STYLES.has(v.lineStyle as string))
@@ -162,6 +185,7 @@ function parseSettingsInput(val: unknown): { ok: SettingsInput } | { err: string
 
 	return {
 		ok: {
+			axis: v.axis as SettingsInput['axis'],
 			palette: v.palette as SettingsInput['palette'],
 			lineStyle: v.lineStyle as SettingsInput['lineStyle'],
 			theme: v.theme as SettingsInput['theme'],
@@ -257,12 +281,14 @@ export function parseAlignBody(body: unknown): { ok: AlignRequest } | { err: str
 export function buildAlignUrl(origin: string, req: AlignRequest): AlignResult {
 	const defaults = defaultVisualSettingsV2();
 
-	// Merge settings overrides
+	// Merge settings overrides. `axis` is spelled differently inside (`layoutAxis`), so it is
+	// pulled out of the spread and mapped by hand; leaving it in would add a stray key that the
+	// compact encoder silently drops.
+	const { axis, ...spreadableSettings } = req.settings ?? {};
 	const visualSettings: VisualSettingsV2 = {
 		...defaults,
-		...(req.settings
-			? Object.fromEntries(Object.entries(req.settings).filter(([, v]) => v !== undefined))
-			: {})
+		...Object.fromEntries(Object.entries(spreadableSettings).filter(([, v]) => v !== undefined)),
+		...(axis !== undefined ? { layoutAxis: axis } : {})
 	};
 	// Clamp numeric settings to valid ranges
 	visualSettings.lineThickness = Math.min(8, Math.max(1, visualSettings.lineThickness));
@@ -280,7 +306,10 @@ export function buildAlignUrl(origin: string, req: AlignRequest): AlignResult {
 			font: { family: inp.font ?? DEFAULT_FONT_FAMILY, source: 'google' as const },
 			textSizePx: Math.min(64, Math.max(12, inp.sizePx ?? DEFAULT_TEXT_SIZE_PX)),
 			gapWordPx: Math.min(56, Math.max(0, inp.gapPx ?? DEFAULT_WORD_GAP_PX)),
-			...(inp.rtl ? { rtl: true } : {})
+			...(inp.rtl ? { rtl: true } : {}),
+			...(inp.orientation && inp.orientation !== 'upright'
+				? { textOrientation: inp.orientation }
+				: {})
 		};
 	});
 

bitext/src/lib/mcp/server.ts

@@ -29,15 +29,18 @@ const PREVIEW_WIDTH = 800;
 
 const TOOL_DESCRIPTION = `Create a shareable Word Aligner diagram that shows which words match across two or more stacked lines of text (a translation and its source, an interlinear gloss, IPA, etc.). Returns a URL that opens the interactive diagram, plus a preview image.
 
-Use this when the user wants to translate a phrase and show word correspondences, align a translation with its source (including RTL scripts like Hebrew or Arabic), or build a Leipzig-style interlinear gloss.
+Use this when the user wants to translate a phrase and show word correspondences, align a translation with its source (including RTL scripts like Hebrew or Arabic, or vertically written ones like Japanese and Mongolian), or build a Leipzig-style interlinear gloss.
 
 Word indices are 0-based token positions. Tokenize each line the same way the tool does before assigning indices:
 - Whitespace always splits ("I have been going" -> I[0] have[1] been[2] going[3]).
 - The characters in settings.tokenSplitChars (default ".-|") also split and are then removed from the rendered text, so "go.PST.IPFV" becomes three tokens (go, PST, IPFV) and the dots disappear. For Leipzig glosses set tokenSplitChars to "-|" to keep the dots.
 - Punctuation stays attached by default ("Hello, world!" -> Hello,[0] world![1]).
 - In RTL lines, word 0 is the logically first word (rightmost on screen); index in reading order.
+- Japanese and Chinese are written without spaces and nothing is segmented for you: put spaces where the alignment units should be.
 
-Each alignment is [lineA, wordA, lineB, wordB]; the two lines must be vertically adjacent (|lineA - lineB| = 1). To express many-to-one, list each target word as its own tuple. Tokens that share a connection group get the same color automatically.`;
+For a vertically written script set settings.axis to "columns". Every line then becomes a vertical column and the connectors run sideways. Set orientation per line: "vertical" stacks the characters (Japanese, Chinese), "sideways" rotates the line a quarter turn (traditional Mongolian, and Latin runs inside vertical text), "upright" leaves a translation as horizontal word boxes. The first line is the leftmost column, so for Japanese and Chinese, whose columns read right to left, list the translation first and the script second.
+
+Each alignment is [lineA, wordA, lineB, wordB]; the two lines must be neighbours in the stack (|lineA - lineB| = 1), which means one above the other in rows and side by side in columns. To express many-to-one, list each target word as its own tuple. Tokens that share a connection group get the same color automatically.`;
 
 const LINE_INPUT_SCHEMA = {
 	oneOf: [
@@ -67,6 +70,12 @@ const LINE_INPUT_SCHEMA = {
 				rtl: {
 					type: 'boolean',
 					description: 'Right-to-left layout (Hebrew, Arabic, ...). Default false.'
+				},
+				orientation: {
+					type: 'string',
+					enum: ['upright', 'vertical', 'sideways'],
+					description:
+						'How this line\'s glyphs are set, visible with settings.axis "columns". "vertical" stacks characters (Japanese, Chinese), "sideways" rotates the line (Mongolian). Default "upright".'
 				}
 			}
 		}
@@ -102,6 +111,12 @@ const TOOL_INPUT_SCHEMA = {
 			additionalProperties: false,
 			description: 'Global visual overrides. Unset fields inherit defaults.',
 			properties: {
+				axis: {
+					type: 'string',
+					enum: ['rows', 'columns'],
+					description:
+						'Flow direction of the diagram. "rows" (default) stacks lines downward with vertical connectors. "columns" stands each line up as a vertical column with sideways connectors, for Japanese, Chinese, and Mongolian; the first line is the leftmost column.'
+				},
 				palette: {
 					type: 'string',
 					enum: ['pastel', 'vivid'],

bitext/src/routes/api/+page.svelte

@@ -284,6 +284,22 @@
 						0-based left-to-right in logical order.</td
 					>
 				</tr>
+				<tr class="bg-gray-50/50 dark:bg-gray-800/20">
+					<td class={tdClass}>orientation</td>
+					<td class={tdTypeClass}
+						><span class={codeClass}>upright</span> <span class={codeClass}>vertical</span>
+						<span class={codeClass}>sideways</span></td
+					>
+					<td class={tdTypeClass}>upright</td>
+					<td class={tdDescClass}
+						>How this line's glyphs are set, visible when <span class={codeClass}
+							>settings.axis</span
+						>
+						is <span class={codeClass}>columns</span>. <span class={codeClass}>vertical</span>
+						stacks the characters (Japanese, Chinese); <span class={codeClass}>sideways</span> rotates
+						the whole line a quarter turn (traditional Mongolian, and Latin runs inside vertical text).</td
+					>
+				</tr>
 			</tbody>
 		</table>
 	</div>
@@ -302,6 +318,36 @@
     ]
   }'`}</pre>
 
+	<h3 class={subheadingClass}>Example — Japanese tategaki beside an English translation</h3>
+	<p class="mt-3">
+		<span class={codeClass}>settings.axis</span> turns the whole diagram into columns;
+		<span class={codeClass}>orientation</span> decides which line stacks its characters. The first line
+		is the leftmost column, so the translation comes first and the Japanese lands on the right, where
+		a vertical text belongs.
+	</p>
+	<pre class="{preClass} mt-3">{`curl -X POST ${apiBase}/api/align \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "lines": [
+      { "text": "The cat ate the fish", "sizePx": 26 },
+      { "text": "猫 が 魚 を 食べた", "orientation": "vertical", "font": "Noto Serif JP", "sizePx": 34 }
+    ],
+    "alignments": [
+      [0, 0, 1, 0],
+      [0, 1, 1, 0],
+      [0, 3, 1, 2],
+      [0, 4, 1, 2],
+      [0, 2, 1, 4]
+    ],
+    "settings": { "axis": "columns" }
+  }'`}</pre>
+	<p class="mt-3">
+		Japanese and Chinese are written without spaces and nothing is segmented for you: put spaces
+		where the alignment units should be. For traditional Mongolian use
+		<span class={codeClass}>"orientation": "sideways"</span> instead, and keep the script line first,
+		since its columns read left to right.
+	</p>
+
 	<!-- ── Visual settings ─────────────────────────────────────── -->
 
 	<h2 id="settings" class={headingClass}>Visual settings (SettingsInput)</h2>
@@ -322,6 +368,19 @@
 			</thead>
 			<tbody class="divide-y divide-gray-100 dark:divide-gray-700/60">
 				<tr>
+					<td class={tdClass}>axis</td>
+					<td class={tdTypeClass}
+						><span class={codeClass}>rows</span> <span class={codeClass}>columns</span></td
+					>
+					<td class={tdTypeClass}>rows</td>
+					<td class={tdDescClass}
+						>Flow direction of the diagram. <span class={codeClass}>columns</span> stands every line
+						up as a vertical column and runs the connectors sideways, for Japanese, Chinese, and
+						Mongolian. The first line is the leftmost column, so reorder
+						<span class={codeClass}>lines</span> to move a script to the other side.</td
+					>
+				</tr>
+				<tr class="bg-gray-50/50 dark:bg-gray-800/20">
 					<td class={tdClass}>palette</td>
 					<td class={tdTypeClass}
 						><span class={codeClass}>pastel</span> <span class={codeClass}>vivid</span></td
@@ -441,19 +500,27 @@
 					<td class={tdClass}>upper</td>
 					<td class={tdTypeClass}>integer <em>required</em></td>
 					<td class={tdTypeClass}>—</td>
-					<td class={tdDescClass}>0-based index of the upper line.</td>
+					<td class={tdDescClass}
+						>0-based index of the earlier line in the stack: the upper one in
+						<span class={codeClass}>rows</span>, the left one in
+						<span class={codeClass}>columns</span>.</td
+					>
 				</tr>
 				<tr class="bg-gray-50/50 dark:bg-gray-800/20">
 					<td class={tdClass}>lower</td>
 					<td class={tdTypeClass}>integer <em>required</em></td>
 					<td class={tdTypeClass}>—</td>
-					<td class={tdDescClass}>0-based index of the lower line (must equal upper + 1).</td>
+					<td class={tdDescClass}
+						>0-based index of the next line in the stack (must equal upper + 1): below in
+						<span class={codeClass}>rows</span>, to the right in
+						<span class={codeClass}>columns</span>.</td
+					>
 				</tr>
 				<tr>
 					<td class={tdClass}>gapPx</td>
 					<td class={tdTypeClass}>integer 12–156</td>
 					<td class={tdTypeClass}>120</td>
-					<td class={tdDescClass}>Vertical gap between the two lines in px.</td>
+					<td class={tdDescClass}>Gap between the two lines in px, measured across the stack.</td>
 				</tr>
 				<tr class="bg-gray-50/50 dark:bg-gray-800/20">
 					<td class={tdClass}>showConnectors</td>

bitext/src/routes/api/align/openapi.json/+server.ts

@@ -57,6 +57,28 @@ export const GET: RequestHandler = ({ url }) => {
 											]
 										}
 									},
+									verticalJapanese: {
+										summary: 'Japanese tategaki beside an English translation',
+										value: {
+											lines: [
+												{ text: 'The cat ate the fish', sizePx: 26 },
+												{
+													text: '猫 が 魚 を 食べた',
+													orientation: 'vertical',
+													font: 'Noto Serif JP',
+													sizePx: 34
+												}
+											],
+											alignments: [
+												[0, 0, 1, 0],
+												[0, 1, 1, 0],
+												[0, 3, 1, 2],
+												[0, 4, 1, 2],
+												[0, 2, 1, 4]
+											],
+											settings: { axis: 'columns' }
+										}
+									},
 									multiLine: {
 										summary: '3 lines, gloss row with larger gap',
 										value: {
@@ -158,6 +180,12 @@ export const GET: RequestHandler = ({ url }) => {
 								rtl: {
 									type: 'boolean',
 									description: 'Right-to-left layout for Hebrew, Arabic, etc. Defaults to false.'
+								},
+								orientation: {
+									type: 'string',
+									enum: ['upright', 'vertical', 'sideways'],
+									description:
+										'How this line\'s glyphs are set, visible when settings.axis is "columns". "vertical" stacks the characters (Japanese, Chinese); "sideways" rotates the line a quarter turn (traditional Mongolian, and Latin runs inside vertical text). Defaults to upright.'
 								}
 							}
 						}
@@ -167,6 +195,12 @@ export const GET: RequestHandler = ({ url }) => {
 					type: 'object',
 					description: 'Visual settings overrides. Unset fields inherit defaults.',
 					properties: {
+						axis: {
+							type: 'string',
+							enum: ['rows', 'columns'],
+							description:
+								'Flow direction of the diagram. "rows" stacks lines downward with vertical connectors. "columns" stands every line up as a vertical column with sideways connectors, for Japanese, Chinese, and Mongolian; the first line is the leftmost column, so reorder lines to move a script to the other side. Default: rows.'
+						},
 						palette: {
 							type: 'string',
 							enum: ['pastel', 'vivid'],