chore: align Vue file conventions (#137)

- document Vue file authoring conventions
- rename runtime/example component files to kebab-case
- update imports and docs references

.agents/docs/ink-divergences.md

@@ -221,7 +221,7 @@ reactivity, lifecycle, component boundaries, current-props model, or API convent
 
 - **Principle:** vue-tui validates invalid render input (a chalk-**modifier**
   `backgroundColor` like `"bold"`, an unknown `borderStyle`) at the
-  **component-render layer** (`Box.ts` / `Text.ts`), not down at the **paint layer**. A bad
+  **component-render layer** (`box.ts` / `text.ts`), not down at the **paint layer**. A bad
   value therefore throws where the **error boundary** catches it -> `ErrorOverview` -> a
   clean `reject` of `waitUntilExit()`, exactly like any other component error. The app
   reports the error instead of crashing.
@@ -460,8 +460,6 @@ These notes are not divergence entries. They document Vue-facing conventions or
 mechanics so they are not mistaken for parity gaps.
 
 - Vue SFCs use `<script setup>`, and component definitions use `defineComponent()`.
-- Filenames use kebab-case.
-- Files use `.ts` over `.tsx` where there is no JSX.
 - `shallowRef` is the default for reactive state. Use `ref` only when deep reactivity is
   intentional and documented.
 - Commit timing is deliberately Ink-aligned: leading+trailing throttle at

AGENTS.md

@@ -4,6 +4,8 @@
 - Always use Vue's `shallowRef` over `ref` by default. Using `ref` requires a solid justification and a code comment explaining why deep reactivity is needed.
 - Always use `defineComponent()` to define components. Never use bare `{ setup() {} }` objects — they lack component scope, so `inject`, `watch`, and `onScopeDispose` won't work correctly.
 - Vue SFCs must use `<script setup>` unless there's an explicit reason not to.
+- For ordinary Vue UI, start with template syntax. Use JSX/TSX when it makes test fixtures or highly dynamic structures clearer, and reserve `h()` for renderer internals or genuinely programmatic vnode construction where template/JSX would be the wrong tool.
+- Prefer kebab-case for new file names, including Vue SFCs and JSX/TSX files. Keep local consistency when touching existing areas, and do not rename existing files only for casing unless the task is explicitly about naming.
 - When code must deviate from normal/idiomatic style because the situation genuinely requires it (e.g. a control-character regex in a terminal parser, a deliberate string code-point spread, a lint rule suppressed for a justified reason), add a comment explaining _why_ it has to be written that way. Don't silence a linter or write surprising code without a note — the next reader should not have to guess whether it's intentional.
 - Bug fixes must follow test-first: write a failing test that reproduces the bug, then fix the code and verify the test passes.
 - Tests must simulate real user conditions. Non-TTY environments disable chalk colors — use `FORCE_COLOR` env var so ANSI output is always exercised. A bug invisible in tests but visible in a real terminal is a testing gap, not a minor issue. Each spawned subprocess is a fresh Node process with its own chalk, so PTY/child helpers must set `FORCE_COLOR` in the child env too, not just the vitest config.

README.md

@@ -32,20 +32,20 @@ npm install
 npm run dev
 ```
 
-Edit `App.vue` and watch the terminal update instantly.
+Edit `app.vue` and watch the terminal update instantly.
 
 ## Example
 
 ```ts
 // src/main.ts
 import { createApp } from "@vue-tui/runtime";
-import App from "./App.vue";
+import App from "./app.vue";
 
 createApp(App).mount();
 ```
 
 ```vue
-<!-- src/App.vue -->
+<!-- src/app.vue -->
 <script setup lang="ts">
 import { shallowRef } from "vue";
 import { Box, Text, useInput } from "@vue-tui/runtime";

examples/basic-jsx/src/app.tsx

@@ -1,7 +1,7 @@
 import { shallowRef, defineComponent } from "vue";
 import { Box, Text, useInput } from "@vue-tui/runtime";
-import Counter from "./Counter";
-import Clock from "./Clock";
+import Counter from "./counter";
+import Clock from "./clock";
 
 export default defineComponent(() => {
   const showClock = shallowRef(true);
@@ -16,7 +16,7 @@ export default defineComponent(() => {
       <Text bold color="cyan">
         vue-tui basic (JSX)
       </Text>
-      <Text dimColor>Try editing Counter.tsx or App.tsx</Text>
+      <Text dimColor>Try editing counter.tsx or app.tsx</Text>
       <Text dimColor>Press c=toggle clock, q=quit</Text>
       <Text> </Text>
       <Counter />

examples/basic-jsx/src/main.tsx

@@ -1,4 +1,4 @@
 import { createApp } from "@vue-tui/runtime";
-import App from "./App";
+import App from "./app";
 
 createApp(App).mount();

examples/basic-template/src/app.vue

@@ -1,8 +1,8 @@
 <script setup lang="ts">
 import { shallowRef } from "vue";
 import { Box, Text, useInput } from "@vue-tui/runtime";
-import Counter from "./Counter.vue";
-import Clock from "./Clock.vue";
+import Counter from "./counter.vue";
+import Clock from "./clock.vue";
 
 const showClock = shallowRef(true);
 
@@ -15,7 +15,7 @@ useInput((input) => {
 <template>
   <Box backgroundColor="blue" borderStyle="round" width="20">
     <Text bold color="cyan">vue-tui basic (template)</Text>
-    <Text dimColor>Try editing Counter.vue or App.vue</Text>
+    <Text dimColor>Try editing counter.vue or app.vue</Text>
     <Text dimColor>Press c=toggle clock, q=quit</Text>
     <Text> </Text>
     <Counter />

examples/basic-template/src/main.ts

@@ -1,4 +1,4 @@
 import { createApp } from "@vue-tui/runtime";
-import App from "./App.vue";
+import App from "./app.vue";
 
 createApp(App).mount();

examples/coding-agent/src/app.vue

@@ -2,7 +2,7 @@
 import { shallowRef } from "vue";
 import { Box, Text, Static, useInput, useApp } from "@vue-tui/runtime";
 import { runAgentLoop, type Message, type ToolCall } from "./agent";
-import MessageList from "./components/MessageList.vue";
+import MessageList from "./components/message-list.vue";
 
 type AppState = "idle" | "streaming" | "approving";
 

examples/coding-agent/src/main.ts

@@ -1,5 +1,5 @@
 import { createApp } from "@vue-tui/runtime";
-import App from "./App.vue";
+import App from "./app.vue";
 
 if (!process.env["DEEPSEEK_API_KEY"]) {
   console.error("Error: DEEPSEEK_API_KEY environment variable is required.");

examples/flappy-bird/src/main.ts

@@ -5,6 +5,6 @@
 // Controls: space / ↑ / w to flap, q or Ctrl-C to quit, r to restart after dying.
 
 import { createApp } from "@vue-tui/runtime";
-import App from "./App.vue";
+import App from "./app.vue";
 
 createApp(App).mount();

packages/runtime-tests/integration/accessibility/screen-reader.test.tsx

@@ -1131,7 +1131,7 @@ describe("screen reader enabled mode", () => {
 // suite above did not already cover.
 describe("screen reader: Ink test/screen-reader.tsx parity (component path)", () => {
   // Ink screen-reader.tsx:78-84 — aria-label-only <Text> (no children) emits the
-  // label. Component path: Text.ts substitutes ariaLabel for an absent default slot.
+  // label. Component path: text.ts substitutes ariaLabel for an absent default slot.
   test("aria-label-only Text (no children) emits the label", () => {
     const output = renderToString(
       defineComponent(() => () => <Text aria-label="Screen-reader only" />),
@@ -1141,7 +1141,7 @@ describe("screen reader: Ink test/screen-reader.tsx parity (component path)", ()
   });
 
   // Ink screen-reader.tsx:86-92 — aria-label-only <Box> (no children) emits the
-  // label. Component path: Box.ts builds a label text node when SR + ariaLabel and
+  // label. Component path: box.ts builds a label text node when SR + ariaLabel and
   // there is no default slot.
   test("aria-label-only Box (no children) emits the label", () => {
     const output = renderToString(

packages/runtime-tests/integration/components/borders.test.tsx

@@ -1390,7 +1390,7 @@ test("G16: per-edge borderDimColor=false overrides general borderDimColor", asyn
 // reserved a 1-cell inset). Ink's render-border.ts has no existence check: it
 // reads box.topLeft/box.top off `cliBoxes[name]` === undefined and crashes with a
 // TypeError. We align by throwing a clear, descriptive Error — but do it in the
-// Box component's RENDER (Box.ts), so the throw is caught by vue-tui's existing
+// Box component's RENDER (box.ts), so the throw is caught by vue-tui's existing
 // error boundary (onErrorCaptured → ErrorOverview → exit), exactly like any other
 // component render error. paint.ts stays a silent `if (!chars) return` fallback
 // (a raw throw in the post-flush commit would wedge Vue's scheduler).

packages/runtime-tests/integration/components/static.test.tsx

@@ -818,7 +818,7 @@ test("two separate <Static> regions both render their items (additive divergence
 // B04(a) — the render-prop's SECOND arg (`index`) is the ABSOLUTE array index,
 // stable across INCREMENTAL appends.
 //
-// Static.ts renders `items.slice(cursor)` and passes `index = cursor + i`, where
+// static.ts renders `items.slice(cursor)` and passes `index = cursor + i`, where
 // the cursor advances to items.length after each batch is written. So an item's
 // index is its position in the FULL list, never its position within the append
 // batch. This mirrors Ink's Static, which renders `items.slice(index)` and passes
@@ -869,7 +869,7 @@ test("Static render-prop index is the absolute array index across incremental ap
 
 // B04(b) — vertical padding on the <Static> container paints into the static frame.
 //
-// Static.ts merges the caller `style` onto the internal static box, and
+// static.ts merges the caller `style` onto the internal static box, and
 // static-channel.ts paints that node via its OWN yoga node (paintIsolated). So
 // paddingTop/paddingBottom resolve as real layout: they add blank rows above /
 // below the item inside the painted static frame. Confirmed against the pinned

packages/runtime-tests/integration/components/text.test.tsx

@@ -565,7 +565,7 @@ test("strip complete ESC#8 (DECALN) sequence without clipping at a tight width",
   expect(stripAnsi(output)).toBe("ABC");
 });
 
-// Mirrors Ink text.tsx:277-283 ("strip complete ESC control sequences with
+// Mirrors Ink Text.tsx:277-283 ("strip complete ESC control sequences with
 // intermediates"). The existing ESC#8-only test above misses the ESC-c (RIS, full
 // terminal reset) leg: sanitizeAnsi must strip BOTH the intermediate-byte ESC#8 and
 // the bare ESC c so neither leaks into the painted frame, leaving the visible "ABC".

packages/runtime/README.md

@@ -27,13 +27,13 @@ npm install @vue-tui/runtime vue
 ```ts
 // src/main.ts
 import { createApp } from "@vue-tui/runtime";
-import App from "./App.vue";
+import App from "./app.vue";
 
 createApp(App).mount();
 ```
 
 ```vue
-<!-- src/App.vue -->
+<!-- src/app.vue -->
 <script setup lang="ts">
 import { shallowRef } from "vue";
 import { Box, Text, useInput } from "@vue-tui/runtime";

packages/runtime/src/components/error-overview.ts

@@ -3,8 +3,8 @@ import { cwd } from "node:process";
 import { defineComponent, h, type PropType } from "vue";
 import StackUtils from "stack-utils";
 import codeExcerpt, { type CodeExcerpt } from "code-excerpt";
-import { Box } from "./Box.ts";
-import { Text } from "./Text.ts";
+import { Box } from "./box.ts";
+import { Text } from "./text.ts";
 
 // Ported from Ink's src/components/ErrorOverview.tsx (v7.0.4). We use the <Box>
 // and <Text> wrapper components (not raw host elements) because Ink does, and

packages/runtime/src/host/node-ops.ts

@@ -418,7 +418,7 @@ export function buildNodeOps(options: TtyRendererOptions): RendererOptions<TuiNo
         key === "ariaHidden" ||
         key === "accessibilityLabel"
       ) {
-        // Handled at the Vue component level (Box.ts / Text.ts / Transform.ts),
+        // Handled at the Vue component level (box.ts / text.ts / transform.ts),
         // not stored on the DOM node. Silently ignore so we don't warn.
       } else if (key === "key" || key === "ref" || key.startsWith("on")) {
         // Reserved by Vue / event keys, ignore.

packages/runtime/src/host/text-measure.test.ts

@@ -5,8 +5,8 @@ import wrapAnsi from "wrap-ansi";
 import { createText, createTextLeaf, createTransform, createVirtualText } from "./nodes.ts";
 import { flattenLeaves, measureTextNatural, wrapText } from "./text-measure.ts";
 import { renderToString } from "../render-to-string.ts";
-import { Box } from "../components/Box.ts";
-import { Text } from "../components/Text.ts";
+import { Box } from "../components/box.ts";
+import { Text } from "../components/text.ts";
 
 // Minimal ANSI-stripping helper for test assertions (avoids strip-ansi dep).
 function stripAnsi(s: string): string {

packages/runtime/src/index.ts

@@ -7,12 +7,12 @@ export {
   type AriaState,
   type BoxStyle,
   type BoxProps,
-} from "./components/Box.ts";
-export { Text, type TextProps } from "./components/Text.ts";
-export { Newline, type NewlineProps } from "./components/Newline.ts";
-export { Spacer } from "./components/Spacer.ts";
-export { Static, type StaticProps } from "./components/Static.ts";
-export { Transform, type TransformProps } from "./components/Transform.ts";
+} from "./components/box.ts";
+export { Text, type TextProps } from "./components/text.ts";
+export { Newline, type NewlineProps } from "./components/newline.ts";
+export { Spacer } from "./components/spacer.ts";
+export { Static, type StaticProps } from "./components/static.ts";
+export { Transform, type TransformProps } from "./components/transform.ts";
 
 export { useApp, type UseAppReturn } from "./composables/useApp.ts";
 export { useInput, type Key, type UseInputOptions } from "./composables/useInput.ts";

packages/runtime/src/overlay.ts

@@ -1,6 +1,6 @@
 import { defineComponent, h, inject, type Component, type PropType } from "@vue/runtime-core";
-import { Box } from "./components/Box.ts";
-import { Text } from "./components/Text.ts";
+import { Box } from "./components/box.ts";
+import { Text } from "./components/text.ts";
 import { DevStateKey, type DevState } from "./hmr.ts";
 
 const ErrorDisplay = defineComponent({

packages/runtime/src/paint/static-channel.ts

@@ -76,7 +76,7 @@ export function paintStaticNode(
       // exactly how screen-reader.ts linearizes a box/root container of these
       // children (screen-reader.ts:73-82): the separator and child order derive
       // from the container's resolved flexDirection (defaulting to the
-      // <Static> "column" default set in Static.ts).
+      // <Static> "column" default set in static.ts).
       const flexDirection = resolvedFlexDirection(stat);
       // Match screen-reader.ts:76 exactly — row/row-reverse use a space, all
       // other directions (incl. the column default) use a newline.

packages/runtime/src/render.ts

@@ -43,7 +43,7 @@ import {
 } from "./context.ts";
 import { devState, DevStateKey, initHmrBridge } from "./hmr.ts";
 import { createDevOverlayWrapper } from "./overlay.ts";
-import { ErrorOverview } from "./components/ErrorOverview.ts";
+import { ErrorOverview } from "./components/error-overview.ts";
 import { resolveSize } from "./composables/useTerminalSize.ts";
 
 export interface MountOptions {