@dropsh/plugin-tui 0.5.2

package/LICENSE

@@ -0,0 +1,51 @@
+drupal-cli is dual-licensed. You may use this software under the terms of
+either the MIT License or the GNU General Public License version 2 or any
+later version, at your option.
+
+SPDX-License-Identifier: (MIT OR GPL-2.0-or-later)
+
+================================================================================
+MIT License
+================================================================================
+
+Copyright (c) 2026 Christian Wiedemann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+================================================================================
+GNU General Public License, version 2 or later
+================================================================================
+
+The full text of the GNU GPL v2 is available at:
+  https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
+
+The full text of any later GPL version is available at:
+  https://www.gnu.org/licenses/
+
+Copyright (C) 2026 Christian Wiedemann
+
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+details.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@dropsh/plugin-tui",
+  "version": "0.5.2",
+  "type": "module",
+  "main": "./dist/plugins/tui/src/index.js",
+  "exports": {
+    ".": "./dist/plugins/tui/src/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "dropsh": "*"
+  },
+  "dependencies": {
+    "ink": "^5.0.0",
+    "react": "^18.3.0",
+    "@dropsh/plugin-markdown": "0.5.2"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0",
+    "dropsh": "0.5.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/browse-app.tsx

@@ -0,0 +1,94 @@
+import { Box, Text, useInput } from "ink";
+import type React from "react";
+import { useState } from "react";
+import { FocusRegistryProvider, useFocusRegistry } from "./link.js";
+import type { Router } from "./router.js";
+
+export interface BrowseProps {
+  router: Router;
+  onExit: () => void;
+}
+
+// Inner component: has access to the focus registry so Enter can read the
+// focused link target and ask the router to navigate to it.
+function Keys({
+  router,
+  onExit,
+  focusedIndex,
+  setFocusedIndex,
+  bump,
+  setError,
+  setNavSeq,
+}: {
+  router: Router;
+  onExit: () => void;
+  focusedIndex: number;
+  setFocusedIndex: (fn: (i: number) => number) => void;
+  bump: () => void;
+  setError: (msg: string | null) => void;
+  setNavSeq: (fn: (n: number) => number) => void;
+}): null {
+  const reg = useFocusRegistry();
+  useInput((input, key) => {
+    if (input === "q" || key.escape) {
+      const hasMore = router.back();
+      if (!hasMore) onExit();
+      else {
+        setFocusedIndex(() => 0);
+        setError(null);
+        setNavSeq((n) => n + 1);
+        bump();
+      }
+      return;
+    }
+    if (key.upArrow) setFocusedIndex((i) => Math.max(0, i - 1));
+    if (key.downArrow) setFocusedIndex((i) => Math.min(Math.max(0, reg.count() - 1), i + 1));
+    if (key.return) {
+      const target = reg.targetAt(focusedIndex);
+      if (target) {
+        void router
+          .navigate(target.route, target.params)
+          .then(() => {
+            setFocusedIndex(() => 0);
+            setError(null);
+            setNavSeq((n) => n + 1);
+            bump();
+          })
+          .catch((err: unknown) => {
+            setError(err instanceof Error ? err.message : String(err));
+            bump();
+          });
+      }
+    }
+  });
+  return null;
+}
+
+export function Browse({ router, onExit }: BrowseProps): React.ReactElement {
+  const [focusedIndex, setFocusedIndex] = useState(0);
+  const [, setNonce] = useState(0);
+  const [error, setError] = useState<string | null>(null);
+  const [navSeq, setNavSeq] = useState(0);
+  const bump = () => setNonce((n) => n + 1);
+  const element = router.current();
+  return (
+    <FocusRegistryProvider focusedIndex={focusedIndex}>
+      <Box flexDirection="column">
+        <Box key={navSeq} flexDirection="column">
+          {element}
+        </Box>
+        {error !== null ? <Text color="red">Error: {error}</Text> : null}
+        <Text dimColor>(↑/↓: move, enter: open, q/esc: back)</Text>
+      </Box>
+      <Keys
+        router={router}
+        onExit={onExit}
+        focusedIndex={focusedIndex}
+        setFocusedIndex={setFocusedIndex}
+        bump={bump}
+        setError={setError}
+        setNavSeq={setNavSeq}
+      />
+    </FocusRegistryProvider>
+  );
+}

package/src/entity-list.tsx

@@ -0,0 +1,34 @@
+import type { JsonApiResource } from "dropsh/plugin";
+import { Box, Text } from "ink";
+import React, { type ReactElement } from "react";
+import { label, splitType } from "./jsonapi-type.js";
+import { TuiLink } from "./link.js";
+import type { BuildContext } from "./types.js";
+
+export abstract class TuiEntityList {
+  static entityType: string;
+  static bundle?: string;
+  abstract build(resources: JsonApiResource[], ctx: BuildContext): ReactElement;
+}
+
+export class GenericEntityList extends TuiEntityList {
+  static override entityType = "*";
+
+  build(resources: JsonApiResource[], ctx: BuildContext): ReactElement {
+    if (resources.length === 0) return <Text dimColor>(no results)</Text>;
+    return (
+      <Box flexDirection="column">
+        {resources.map((res) => {
+          const { entityType, bundle } = splitType(res.type);
+          const params: Record<string, string> = { type: entityType, id: res.id };
+          if (bundle) params.bundle = bundle;
+          return (
+            <TuiLink key={res.id} target={ctx.link("entity.canonical", params)}>
+              {label(res)}
+            </TuiLink>
+          );
+        })}
+      </Box>
+    );
+  }
+}

package/src/entity-view.tsx

@@ -0,0 +1,45 @@
+import type { JsonApiResource } from "dropsh/plugin";
+import { Box, Text } from "ink";
+import React, { type ReactElement } from "react";
+import { splitType } from "./jsonapi-type.js";
+import { TuiLink } from "./link.js";
+import type { BuildContext, ViewModeMap } from "./types.js";
+
+export abstract class TuiEntityView {
+  static entityType: string;
+  static bundle?: string;
+  static viewModes: ViewModeMap = { default: {} };
+  abstract build(entity: JsonApiResource, ctx: BuildContext): ReactElement;
+}
+
+export class GenericEntityView extends TuiEntityView {
+  static override entityType = "*";
+  static override viewModes: ViewModeMap = { default: {} };
+
+  build(entity: JsonApiResource, ctx: BuildContext): ReactElement {
+    const attrs = entity.attributes ?? {};
+    const rels = entity.relationships ?? {};
+    return (
+      <Box flexDirection="column">
+        {Object.entries(attrs).map(([key, value]) => (
+          <Text key={`a:${key}`}>
+            {key}: {typeof value === "string" ? value : JSON.stringify(value)}
+          </Text>
+        ))}
+        {Object.entries(rels).map(([key, rel]) => {
+          const data = (rel as { data?: { type: string; id: string } }).data;
+          if (!data || Array.isArray(data)) return <Text key={`r:${key}`}>{key}: —</Text>;
+          const { entityType, bundle } = splitType(data.type);
+          const params: Record<string, string> = { type: entityType, id: data.id };
+          if (bundle) params.bundle = bundle;
+          return (
+            <Box key={`r:${key}`}>
+              <Text>{key}: </Text>
+              <TuiLink target={ctx.link("entity.canonical", params)}>{data.id}</TuiLink>
+            </Box>
+          );
+        })}
+      </Box>
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,94 @@
+import type {
+  DropSHPlugin,
+  JsonApiDocument,
+  JsonApiResource,
+  RenderContext,
+  RenderServices,
+} from "dropsh/plugin";
+import { ConfigError } from "dropsh/plugin";
+import { splitType } from "./jsonapi-type.js";
+import { buildRegistry } from "./registry.js";
+import { createRouter } from "./router.js";
+import type { TuiSubPlugin } from "./types.js";
+
+export { GenericEntityList, TuiEntityList } from "./entity-list.js";
+export { GenericEntityView, TuiEntityView } from "./entity-view.js";
+export { TuiLink } from "./link.js";
+export type {
+  BuildContext,
+  LinkDescriptor,
+  TuiController,
+  TuiRoute,
+  TuiSubPlugin,
+  ViewModeMap,
+} from "./types.js";
+
+export interface TuiOptions {
+  plugins?: TuiSubPlugin[];
+}
+
+function assertTty(isTty: boolean): void {
+  if (!isTty) throw new ConfigError("--format tui requires an interactive terminal");
+}
+
+export function initialTarget(
+  doc: JsonApiDocument,
+  ctx: RenderContext,
+): {
+  route: string;
+  params: Record<string, string>;
+} {
+  if (ctx.command === "search") {
+    const params: Record<string, string> = { type: ctx.entityType ?? "" };
+    if (ctx.bundle) params.bundle = ctx.bundle;
+    return { route: "entity.collection", params };
+  }
+  const first = (Array.isArray(doc.data) ? doc.data[0] : doc.data) as JsonApiResource | undefined;
+  const { entityType, bundle } = splitType(first?.type ?? "");
+  const params: Record<string, string> = { type: entityType, id: first?.id ?? "" };
+  if (bundle) params.bundle = bundle;
+  return { route: "entity.canonical", params };
+}
+
+async function runTui(
+  doc: JsonApiDocument,
+  ctx: RenderContext,
+  opts: TuiOptions,
+  services?: RenderServices,
+): Promise<void> {
+  assertTty(Boolean(process.stdout.isTTY));
+  if (!services) throw new ConfigError("--format tui requires runtime services (client)");
+  const registry = buildRegistry(opts.plugins ?? []);
+  const router = createRouter({
+    registry,
+    client: services.client,
+    viewMode: ctx.viewMode ?? "default",
+  });
+  const target = initialTarget(doc, ctx);
+  await router.navigate(target.route, target.params, doc);
+
+  const [{ render }, React, { Browse }] = await Promise.all([
+    import("ink"),
+    import("react"),
+    import("./browse-app.js"),
+  ]);
+  const app = render(React.createElement(Browse, { router, onExit: () => app.unmount() }));
+  await app.waitUntilExit();
+}
+
+export function tuiPlugin(tuiOpts: TuiOptions = {}): DropSHPlugin {
+  return {
+    id: "tui",
+    requiredModules: [],
+    async extendSchema(_entityType, _bundle, schema) {
+      return schema;
+    },
+    renderers: [
+      {
+        id: "tui",
+        interactive: true,
+        run: (doc, ctx, services) => runTui(doc, ctx, tuiOpts, services),
+      },
+    ],
+  };
+}

package/src/jsonapi-type.ts

@@ -0,0 +1,17 @@
+import type { JsonApiResource } from "dropsh/plugin";
+
+// Splits a JSON:API type "node--article" into { entityType: "node", bundle: "article" }.
+export function splitType(type: string): { entityType: string; bundle?: string } {
+  const [entityType, bundle] = type.split("--") as [string, string?];
+  return bundle ? { entityType, bundle } : { entityType };
+}
+
+// Best-effort human label for a resource: first string-valued title/name/label attribute, else id.
+export function label(res: JsonApiResource): string {
+  const attrs = res.attributes ?? {};
+  for (const key of ["title", "name", "label"]) {
+    const v = attrs[key];
+    if (typeof v === "string") return v;
+  }
+  return res.id;
+}

package/src/link.tsx

@@ -0,0 +1,78 @@
+import { Text } from "ink";
+import type React from "react";
+import { createContext, useContext, useEffect, useMemo, useRef, useState } from "react";
+import type { LinkDescriptor } from "./types.js";
+
+interface Entry {
+  id: symbol;
+  target: LinkDescriptor;
+}
+
+interface FocusRegistry {
+  // register/unregister are called from TuiLink effects, never during render,
+  // so a TuiLink re-rendering without a Provider re-render cannot create
+  // duplicate entries. Registration order (via mount-effect order) is DOM order.
+  register(id: symbol, target: LinkDescriptor): void;
+  unregister(id: symbol): void;
+  indexOf(id: symbol): number;
+  count(): number;
+  focusedIndex: number;
+  targetAt(i: number): LinkDescriptor | undefined;
+}
+
+const Ctx = createContext<FocusRegistry | null>(null);
+
+export function useFocusRegistry(): FocusRegistry {
+  const reg = useContext(Ctx);
+  if (!reg) throw new Error("useFocusRegistry must be used within FocusRegistryProvider");
+  return reg;
+}
+
+export function FocusRegistryProvider({
+  focusedIndex = 0,
+  children,
+}: {
+  focusedIndex?: number;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const [entries, setEntries] = useState<Entry[]>([]);
+  const reg = useMemo<FocusRegistry>(
+    () => ({
+      register(id, target) {
+        setEntries((prev) => (prev.some((e) => e.id === id) ? prev : [...prev, { id, target }]));
+      },
+      unregister(id) {
+        setEntries((prev) => prev.filter((e) => e.id !== id));
+      },
+      indexOf: (id) => entries.findIndex((e) => e.id === id),
+      count: () => entries.length,
+      focusedIndex,
+      targetAt: (i) => entries[i]?.target,
+    }),
+    [entries, focusedIndex],
+  );
+  return <Ctx.Provider value={reg}>{children}</Ctx.Provider>;
+}
+
+export function TuiLink({
+  target,
+  children,
+}: {
+  target: LinkDescriptor;
+  children: React.ReactNode;
+}): React.ReactElement {
+  const reg = useFocusRegistry();
+  const idRef = useRef<symbol | null>(null);
+  if (idRef.current === null) idRef.current = Symbol("tuilink");
+  const id = idRef.current;
+  // Register once on mount, unregister on unmount. A link's target is fixed for
+  // its lifetime (derived from stable entity data), so no per-render update.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: register once on mount only
+  useEffect(() => {
+    reg.register(id, target);
+    return () => reg.unregister(id);
+  }, []);
+  const index = reg.indexOf(id);
+  const isFocused = index === reg.focusedIndex;
+  return <Text inverse={isFocused}>{children}</Text>;
+}

package/src/registry.ts

@@ -0,0 +1,106 @@
+import type { JsonApiDocument, JsonApiResource } from "dropsh/plugin";
+import { DrupalJsonApiParams } from "drupal-jsonapi-params";
+import React from "react";
+import { GenericEntityList, TuiEntityList } from "./entity-list.js";
+import { GenericEntityView, TuiEntityView } from "./entity-view.js";
+import type {
+  ControllerContext,
+  EntityListClass,
+  EntityViewClass,
+  TuiRoute,
+  TuiSubPlugin,
+} from "./types.js";
+
+export interface Registry {
+  resolveView(entityType: string, bundle?: string): EntityViewClass;
+  resolveList(entityType: string, bundle?: string): EntityListClass;
+  routes: Map<string, TuiRoute>;
+}
+
+function key(entityType: string, bundle?: string): string {
+  return `${entityType}:${bundle ?? ""}`;
+}
+
+function isView(c: unknown): c is EntityViewClass {
+  return typeof c === "function" && (c as typeof TuiEntityView).prototype instanceof TuiEntityView;
+}
+function isList(c: unknown): c is EntityListClass {
+  return typeof c === "function" && (c as typeof TuiEntityList).prototype instanceof TuiEntityList;
+}
+
+function buildCtxLink(ctx: ControllerContext) {
+  return {
+    viewMode: ctx.viewMode,
+    link: (route: string, params: Record<string, string>) => ({ route, params }),
+  };
+}
+
+function coreRoutes(): TuiRoute[] {
+  const canonical: TuiRoute = {
+    name: "entity.canonical",
+    path: "/{type}/{bundle}/{id}",
+    controller: async (params, ctx) => {
+      const ViewClass = ctx.resolveView(params.type as string, params.bundle);
+      const include = ViewClass?.viewModes?.[ctx.viewMode]?.include;
+      const path = params.bundle
+        ? `${params.type}/${params.bundle}/${params.id}`
+        : `${params.type}/${params.id}`;
+      const doc = (ctx.seededDoc ??
+        (include?.length
+          ? await ctx.client.get(path, new DrupalJsonApiParams().addInclude(include))
+          : await ctx.client.get(path))) as JsonApiDocument;
+      const entity = (Array.isArray(doc.data) ? doc.data[0] : doc.data) as JsonApiResource;
+      const instance = new (
+        ViewClass as unknown as { new (): { build: TuiEntityView["build"] } }
+      )();
+      return React.createElement(
+        React.Fragment,
+        null,
+        instance.build(entity, { doc, ...buildCtxLink(ctx) }),
+      );
+    },
+  };
+  const collection: TuiRoute = {
+    name: "entity.collection",
+    path: "/{type}",
+    controller: async (params, ctx) => {
+      const ListClass = ctx.resolveList(params.type as string, params.bundle);
+      const doc = (ctx.seededDoc ??
+        (await ctx.client.get(
+          params.bundle ? `${params.type}/${params.bundle}` : (params.type as string),
+        ))) as JsonApiDocument;
+      const rows = (Array.isArray(doc.data) ? doc.data : [doc.data]) as JsonApiResource[];
+      const instance = new (
+        ListClass as unknown as { new (): { build: TuiEntityList["build"] } }
+      )();
+      return React.createElement(
+        React.Fragment,
+        null,
+        instance.build(rows, { doc, ...buildCtxLink(ctx) }),
+      );
+    },
+  };
+  return [canonical, collection];
+}
+
+export function buildRegistry(plugins: TuiSubPlugin[]): Registry {
+  const views = new Map<string, EntityViewClass>();
+  const lists = new Map<string, EntityListClass>();
+  const routes = new Map<string, TuiRoute>();
+
+  for (const r of coreRoutes()) routes.set(r.name, r);
+
+  for (const p of plugins) {
+    for (const entity of p.entities ?? []) {
+      if (isView(entity)) views.set(key(entity.entityType, entity.bundle), entity);
+      else if (isList(entity)) lists.set(key(entity.entityType, entity.bundle), entity);
+    }
+    for (const route of p.routes ?? []) routes.set(route.name, route);
+  }
+
+  return {
+    resolveView: (t, b) => views.get(key(t, b)) ?? views.get(key(t)) ?? GenericEntityView,
+    resolveList: (t, b) => lists.get(key(t, b)) ?? lists.get(key(t)) ?? GenericEntityList,
+    routes,
+  };
+}

package/src/router.ts

@@ -0,0 +1,56 @@
+import type { JsonApiClient } from "dropsh/plugin";
+import type { ReactElement } from "react";
+import type { Registry } from "./registry.js";
+import type { ControllerContext } from "./types.js";
+
+export interface Router {
+  stackDepth(): number;
+  current(): ReactElement | null;
+  navigate(
+    route: string,
+    params: Record<string, string>,
+    seededDoc?: import("dropsh/plugin").JsonApiDocument,
+  ): Promise<void>;
+  back(): boolean;
+}
+
+export function createRouter(opts: {
+  registry: Registry;
+  client: JsonApiClient;
+  viewMode: string;
+}): Router {
+  const stack: ReactElement[] = [];
+
+  async function navigate(
+    routeName: string,
+    params: Record<string, string>,
+    seededDoc?: import("dropsh/plugin").JsonApiDocument,
+  ): Promise<void> {
+    const route = opts.registry.routes.get(routeName);
+    if (!route) throw new Error(`unknown route: ${routeName}`);
+    const ctx: ControllerContext = {
+      client: opts.client,
+      viewMode: opts.viewMode,
+      ...(seededDoc !== undefined ? { seededDoc } : {}),
+      navigate: (r, p) => {
+        // Host-level navigation surfaces errors in the UI; a controller-initiated
+        // navigation failure must not become an unhandled rejection / crash.
+        void navigate(r, p).catch(() => {});
+      },
+      resolveView: opts.registry.resolveView,
+      resolveList: opts.registry.resolveList,
+    };
+    const element = await route.controller(params, ctx);
+    stack.push(element);
+  }
+
+  return {
+    stackDepth: () => stack.length,
+    current: () => stack[stack.length - 1] ?? null,
+    navigate,
+    back() {
+      stack.pop();
+      return stack.length > 0;
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+import type { JsonApiClient, JsonApiDocument } from "dropsh/plugin";
+import type { ReactElement } from "react";
+
+export interface LinkDescriptor {
+  route: string;
+  params: Record<string, string>;
+}
+
+export interface BuildContext {
+  viewMode: string;
+  doc: JsonApiDocument;
+  link(route: string, params: Record<string, string>): LinkDescriptor;
+}
+
+export type ViewModeMap = Record<string, { include?: string[] }>;
+
+export interface ControllerContext {
+  client: JsonApiClient;
+  viewMode: string;
+  seededDoc?: JsonApiDocument;
+  navigate(route: string, params: Record<string, string>): void;
+  resolveView(entityType: string, bundle?: string): EntityViewClass | undefined;
+  resolveList(entityType: string, bundle?: string): EntityListClass | undefined;
+}
+
+export type TuiController = (
+  params: Record<string, string>,
+  ctx: ControllerContext,
+) => Promise<ReactElement>;
+
+export interface TuiRoute {
+  name: string;
+  path: string;
+  controller: TuiController;
+}
+
+// Structural handler class shapes; concrete bases live in entity-view.tsx / entity-list.tsx.
+export interface EntityViewClass {
+  entityType: string;
+  bundle?: string;
+  viewModes: ViewModeMap;
+  new (): {
+    build(entity: import("dropsh/plugin").JsonApiResource, ctx: BuildContext): ReactElement;
+  };
+}
+export interface EntityListClass {
+  entityType: string;
+  bundle?: string;
+  new (): {
+    build(resources: import("dropsh/plugin").JsonApiResource[], ctx: BuildContext): ReactElement;
+  };
+}
+export type EntityHandlerClass = EntityViewClass | EntityListClass;
+
+export interface TuiSubPlugin {
+  id: string;
+  entities?: EntityHandlerClass[];
+  routes?: TuiRoute[];
+}

package/tests/unit/browse-app.test.tsx

@@ -0,0 +1,142 @@
+import type { JsonApiClient } from "dropsh/plugin";
+import { render } from "ink-testing-library";
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { Browse } from "../../src/browse-app.js";
+import { buildRegistry } from "../../src/registry.js";
+import { createRouter } from "../../src/router.js";
+
+function client(): JsonApiClient {
+  return {
+    get: vi.fn(async () => ({
+      data: { type: "node--article", id: "u9", attributes: { title: "Fetched" } },
+    })),
+    post: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+    upload: vi.fn(),
+  } as unknown as JsonApiClient;
+}
+
+const tick = () => new Promise((r) => setTimeout(r, 20));
+
+describe("Browse", () => {
+  it("renders the seeded entity via the generic view", async () => {
+    const c = client();
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate(
+      "entity.canonical",
+      { type: "node", bundle: "article", id: "u1" },
+      {
+        data: {
+          type: "node--article",
+          id: "u1",
+          attributes: { title: "Alpha" },
+          relationships: { uid: { data: { type: "user--user", id: "a1" } } },
+        },
+      },
+    );
+    const { lastFrame } = render(<Browse router={router} onExit={() => {}} />);
+    await tick();
+    expect(lastFrame()).toContain("Alpha");
+    expect(lastFrame()).toContain("uid");
+  });
+
+  it("exits when back() empties the stack", async () => {
+    const c = client();
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate(
+      "entity.canonical",
+      { type: "node", bundle: "article", id: "u1" },
+      {
+        data: { type: "node--article", id: "u1", attributes: { title: "Alpha" } },
+      },
+    );
+    const onExit = vi.fn();
+    const { stdin } = render(<Browse router={router} onExit={onExit} />);
+    await tick();
+    stdin.write("q");
+    await tick();
+    expect(onExit).toHaveBeenCalled();
+  });
+
+  it("surfaces a navigation error instead of crashing", async () => {
+    const c = {
+      get: vi.fn(async () => {
+        throw new Error("boom");
+      }),
+      post: vi.fn(),
+      patch: vi.fn(),
+      delete: vi.fn(),
+      upload: vi.fn(),
+    } as unknown as JsonApiClient;
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate(
+      "entity.canonical",
+      { type: "node", bundle: "article", id: "u1" },
+      {
+        data: {
+          type: "node--article",
+          id: "u1",
+          attributes: { title: "Alpha" },
+          relationships: { uid: { data: { type: "user--user", id: "a1" } } },
+        },
+      },
+    );
+    const { lastFrame, stdin } = render(<Browse router={router} onExit={() => {}} />);
+    await tick();
+    stdin.write("\r"); // Enter → navigate to user/a1 → client.get rejects
+    await tick();
+    expect(lastFrame()).toContain("boom");
+  });
+
+  it("navigates using the newly-rendered entity's links, not the previous entity's (regression)", async () => {
+    const rel = (id: string) => ({
+      field_ref: { data: { type: "node--article", id } },
+    });
+    const get = vi.fn(async (path: string) => {
+      // A already seeded; B links to C; C links to D.
+      if (path === "node/article/B") {
+        return {
+          data: {
+            type: "node--article",
+            id: "B",
+            attributes: { title: "Bee" },
+            relationships: rel("C"),
+          },
+        };
+      }
+      return {
+        data: { type: "node--article", id: path.split("/").pop(), attributes: { title: "X" } },
+      };
+    });
+    const c = {
+      get,
+      post: vi.fn(),
+      patch: vi.fn(),
+      delete: vi.fn(),
+      upload: vi.fn(),
+    } as unknown as JsonApiClient;
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    // Seed A, which links to B.
+    await router.navigate(
+      "entity.canonical",
+      { type: "node", bundle: "article", id: "A" },
+      {
+        data: {
+          type: "node--article",
+          id: "A",
+          attributes: { title: "Ay" },
+          relationships: rel("B"),
+        },
+      },
+    );
+    const { stdin } = render(<Browse router={router} onExit={() => {}} />);
+    await tick();
+    stdin.write("\r"); // Enter on A's field_ref → fetch B
+    await tick();
+    stdin.write("\r"); // Enter on the link now shown for B → must fetch C, NOT B again
+    await tick();
+    expect(get).toHaveBeenCalledWith("node/article/C");
+  });
+});

package/tests/unit/entity-list.test.tsx

@@ -0,0 +1,29 @@
+import type { JsonApiDocument, JsonApiResource } from "dropsh/plugin";
+import { render } from "ink-testing-library";
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { GenericEntityList } from "../../src/entity-list.js";
+import { FocusRegistryProvider } from "../../src/link.js";
+
+const link = (route: string, params: Record<string, string>) => ({ route, params });
+
+describe("GenericEntityList", () => {
+  it("renders one navigable row per resource with a title label", () => {
+    const rows: JsonApiResource[] = [
+      { type: "node--article", id: "u1", attributes: { title: "Alpha" } },
+      { type: "node--article", id: "u2", attributes: { title: "Beta" } },
+    ];
+    const doc: JsonApiDocument = { data: rows };
+    const el = new GenericEntityList().build(rows, { viewMode: "default", doc, link });
+    const { lastFrame } = render(<FocusRegistryProvider>{el}</FocusRegistryProvider>);
+    expect(lastFrame()).toContain("Alpha");
+    expect(lastFrame()).toContain("Beta");
+  });
+
+  it("shows (no results) for an empty collection", () => {
+    const doc: JsonApiDocument = { data: [] };
+    const el = new GenericEntityList().build([], { viewMode: "default", doc, link });
+    const { lastFrame } = render(<FocusRegistryProvider>{el}</FocusRegistryProvider>);
+    expect(lastFrame()).toContain("(no results)");
+  });
+});

package/tests/unit/entity-view.test.tsx

@@ -0,0 +1,29 @@
+import type { JsonApiDocument, JsonApiResource } from "dropsh/plugin";
+import { render } from "ink-testing-library";
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { GenericEntityView } from "../../src/entity-view.js";
+import { FocusRegistryProvider } from "../../src/link.js";
+
+const link = (route: string, params: Record<string, string>) => ({ route, params });
+
+function ctx(doc: JsonApiDocument) {
+  return { viewMode: "default", doc, link };
+}
+
+describe("GenericEntityView", () => {
+  it("renders attributes and a navigable relationship", () => {
+    const entity: JsonApiResource = {
+      type: "node--article",
+      id: "u1",
+      attributes: { title: "Alpha" },
+      relationships: { uid: { data: { type: "user--user", id: "a1" } } },
+    };
+    const doc: JsonApiDocument = { data: entity };
+    const el = new GenericEntityView().build(entity, ctx(doc));
+    const { lastFrame } = render(<FocusRegistryProvider>{el}</FocusRegistryProvider>);
+    expect(lastFrame()).toContain("title");
+    expect(lastFrame()).toContain("Alpha");
+    expect(lastFrame()).toContain("uid");
+  });
+});

package/tests/unit/index.test.tsx

@@ -0,0 +1,77 @@
+import type { JsonApiDocument, RenderContext, RenderServices } from "dropsh/plugin";
+import { describe, expect, it, vi } from "vitest";
+import { initialTarget, tuiPlugin } from "../../src/index.js";
+
+function services(): RenderServices {
+  return {
+    client: { get: vi.fn(async () => ({ data: [] })) } as never,
+    baseUrl: "https://x.test",
+  };
+}
+
+describe("tuiPlugin", () => {
+  it("exposes an interactive renderer with id 'tui'", () => {
+    const plugin = tuiPlugin();
+    const renderer = plugin.renderers?.[0];
+    expect(renderer?.id).toBe("tui");
+    expect((renderer as { interactive?: boolean }).interactive).toBe(true);
+  });
+
+  it("run() rejects when stdout is not a TTY", async () => {
+    const plugin = tuiPlugin();
+    const renderer = plugin.renderers?.[0] as {
+      run: (d: JsonApiDocument, c: RenderContext, s?: RenderServices) => Promise<void>;
+    };
+    const orig = process.stdout.isTTY;
+    Object.defineProperty(process.stdout, "isTTY", { value: false, configurable: true });
+    await expect(
+      renderer.run({ data: { type: "node--article", id: "u1" } }, { command: "read" }, services()),
+    ).rejects.toThrow(/interactive terminal/i);
+    Object.defineProperty(process.stdout, "isTTY", { value: orig, configurable: true });
+  });
+});
+
+describe("initialTarget", () => {
+  it("read of a single resource → canonical route with type/bundle/id", () => {
+    const t = initialTarget({ data: { type: "node--article", id: "u1" } }, {
+      command: "read",
+    } as RenderContext);
+    expect(t).toEqual({
+      route: "entity.canonical",
+      params: { type: "node", bundle: "article", id: "u1" },
+    });
+  });
+
+  it("read of a collection → canonical route for the first resource", () => {
+    const t = initialTarget(
+      {
+        data: [
+          { type: "node--page", id: "p1" },
+          { type: "node--page", id: "p2" },
+        ],
+      },
+      { command: "read" } as RenderContext,
+    );
+    expect(t).toEqual({
+      route: "entity.canonical",
+      params: { type: "node", bundle: "page", id: "p1" },
+    });
+  });
+
+  it("search → collection route with type and bundle from ctx", () => {
+    const t = initialTarget({ data: [] }, {
+      command: "search",
+      entityType: "node",
+      bundle: "article",
+    } as RenderContext);
+    expect(t).toEqual({ route: "entity.collection", params: { type: "node", bundle: "article" } });
+  });
+
+  it("search without a bundle → collection route with only type", () => {
+    const t = initialTarget({ data: [] }, {
+      command: "search",
+      entityType: "node",
+    } as RenderContext);
+    expect(t).toEqual({ route: "entity.collection", params: { type: "node" } });
+  });
+});

package/tests/unit/jsonapi-type.test.ts

@@ -0,0 +1,24 @@
+import type { JsonApiResource } from "dropsh/plugin";
+import { describe, expect, it } from "vitest";
+import { label, splitType } from "../../src/jsonapi-type.js";
+
+describe("splitType", () => {
+  it("splits type--bundle", () => {
+    expect(splitType("node--article")).toEqual({ entityType: "node", bundle: "article" });
+  });
+  it("handles a type with no bundle segment", () => {
+    expect(splitType("user")).toEqual({ entityType: "user" });
+  });
+});
+
+describe("label", () => {
+  it("prefers title, then name, then label, else id", () => {
+    expect(label({ type: "n--a", id: "1", attributes: { title: "T" } } as JsonApiResource)).toBe(
+      "T",
+    );
+    expect(label({ type: "n--a", id: "1", attributes: { name: "N" } } as JsonApiResource)).toBe(
+      "N",
+    );
+    expect(label({ type: "n--a", id: "1", attributes: {} } as JsonApiResource)).toBe("1");
+  });
+});

package/tests/unit/link.test.tsx

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+
+// Force chalk (used internally by ink to render styles such as `inverse`) to
+// emit real ANSI escapes even though tests run outside a TTY. This must be
+// set before ink — and anything that imports it — is loaded, so those
+// modules are imported dynamically below, after this line runs.
+process.env.FORCE_COLOR = "1";
+
+const { Text } = await import("ink");
+const { render } = await import("ink-testing-library");
+const { FocusRegistryProvider, TuiLink, useFocusRegistry } = await import("../../src/link.js");
+
+const tick = () => new Promise((r) => setTimeout(r, 30));
+
+// Renders the registry's observable state so the test can assert registration
+// count and which target is focused — after mount effects have run.
+function Probe() {
+  const reg = useFocusRegistry();
+  return (
+    <Text>
+      count={reg.count()} focus={reg.targetAt(reg.focusedIndex)?.params.id ?? "none"}
+    </Text>
+  );
+}
+
+function tree(focusedIndex: number) {
+  return (
+    <FocusRegistryProvider focusedIndex={focusedIndex}>
+      <TuiLink target={{ route: "entity.canonical", params: { id: "u1" } }}>Alpha</TuiLink>
+      <TuiLink target={{ route: "entity.canonical", params: { id: "u2" } }}>Beta</TuiLink>
+      <Probe />
+    </FocusRegistryProvider>
+  );
+}
+
+describe("TuiLink + FocusRegistry", () => {
+  it("registers each link once, in order, and resolves the focused target", async () => {
+    const { lastFrame } = render(tree(1));
+    await tick();
+    expect(lastFrame()).toContain("Alpha");
+    expect(lastFrame()).toContain("Beta");
+    // Both links registered exactly once (no render-time duplicate registration).
+    expect(lastFrame()).toContain("count=2");
+    // focusedIndex 1 resolves to the second registered link (Beta / u2), proving
+    // registration order is DOM order and targetAt/focusedIndex wiring works.
+    expect(lastFrame()).toContain("focus=u2");
+  });
+
+  it("wraps only the focused link in inverse styling", async () => {
+    const a = render(tree(0));
+    await tick();
+    const f0 = a.lastFrame() ?? "";
+    const b = render(tree(1));
+    await tick();
+    const f1 = b.lastFrame() ?? "";
+    const INV = ""; // ANSI SGR: inverse on
+    // focusedIndex 0 → only "Alpha" is highlighted.
+    expect(f0).toContain(`${INV}Alpha`);
+    expect(f0).not.toContain(`${INV}Beta`);
+    // focusedIndex 1 → only "Beta" is highlighted.
+    expect(f1).toContain(`${INV}Beta`);
+    expect(f1).not.toContain(`${INV}Alpha`);
+  });
+});

package/tests/unit/registry.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { GenericEntityList } from "../../src/entity-list.js";
+import { GenericEntityView, TuiEntityView } from "../../src/entity-view.js";
+import { buildRegistry } from "../../src/registry.js";
+
+class ArticleView extends TuiEntityView {
+  static override entityType = "node";
+  static override bundle = "article";
+  static override viewModes = { default: {}, teaser: {} };
+  build() {
+    return null as never;
+  }
+}
+
+describe("buildRegistry", () => {
+  it("resolves a registered view by type+bundle, else the generic default", () => {
+    const reg = buildRegistry([{ id: "x", entities: [ArticleView] }]);
+    expect(reg.resolveView("node", "article")).toBe(ArticleView);
+    expect(reg.resolveView("node", "page")).toBe(GenericEntityView);
+    expect(reg.resolveView("user")).toBe(GenericEntityView);
+    expect(reg.resolveList("node", "article")).toBe(GenericEntityList);
+  });
+
+  it("provides core default routes and lets sub-plugin routes override by name", () => {
+    const custom = {
+      name: "entity.canonical",
+      path: "/custom/{id}",
+      controller: async () => null as never,
+    };
+    const reg = buildRegistry([{ id: "x", routes: [custom] }]);
+    expect(reg.routes.get("entity.collection")?.path).toBe("/{type}");
+    expect(reg.routes.get("entity.canonical")).toBe(custom);
+  });
+});

package/tests/unit/router.test.ts

@@ -0,0 +1,91 @@
+import type { JsonApiClient } from "dropsh/plugin";
+import { describe, expect, it, vi } from "vitest";
+import { TuiEntityView } from "../../src/entity-view.js";
+import { buildRegistry } from "../../src/registry.js";
+import { createRouter } from "../../src/router.js";
+
+function client(): JsonApiClient {
+  return {
+    get: vi.fn(async (path: string) => ({
+      data: { type: "node--article", id: path.split("/").pop() ?? "x" },
+    })),
+    post: vi.fn(),
+    patch: vi.fn(),
+    delete: vi.fn(),
+    upload: vi.fn(),
+  } as unknown as JsonApiClient;
+}
+
+describe("createRouter", () => {
+  it("uses the seeded doc without fetching on the first navigate", async () => {
+    const c = client();
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate(
+      "entity.canonical",
+      { type: "node", bundle: "article", id: "u1" },
+      {
+        data: { type: "node--article", id: "u1", attributes: { title: "Seed" } },
+      },
+    );
+    expect(router.stackDepth()).toBe(1);
+    expect(c.get).not.toHaveBeenCalled();
+  });
+
+  it("fetches (upcasts) when navigating without a seeded doc, and back() pops", async () => {
+    const c = client();
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate("entity.canonical", { type: "node", bundle: "article", id: "u1" });
+    await router.navigate("entity.canonical", { type: "user", id: "a1" });
+    expect(c.get).toHaveBeenCalledTimes(2);
+    expect(router.stackDepth()).toBe(2);
+    expect(router.back()).toBe(true);
+    expect(router.stackDepth()).toBe(1);
+    expect(router.back()).toBe(false);
+  });
+
+  it("throws on an unknown route name", async () => {
+    const router = createRouter({
+      registry: buildRegistry([]),
+      client: client(),
+      viewMode: "default",
+    });
+    await expect(router.navigate("nope", {})).rejects.toThrow(/unknown route/i);
+  });
+
+  it("passes the view mode's include hints to client.get on a non-seeded canonical fetch", async () => {
+    class ArticleView extends TuiEntityView {
+      static override entityType = "node";
+      static override bundle = "article";
+      static override viewModes = { default: { include: ["uid"] } };
+      build() {
+        return null as never;
+      }
+    }
+    const get = vi.fn(
+      async (_path: string, _params?: import("drupal-jsonapi-params").DrupalJsonApiParams) => ({
+        data: { type: "node--article", id: "x" },
+      }),
+    );
+    const c = {
+      get,
+      post: vi.fn(),
+      patch: vi.fn(),
+      delete: vi.fn(),
+      upload: vi.fn(),
+    } as unknown as JsonApiClient;
+    const router = createRouter({
+      registry: buildRegistry([{ id: "x", entities: [ArticleView] }]),
+      client: c,
+      viewMode: "default",
+    });
+    await router.navigate("entity.canonical", { type: "node", bundle: "article", id: "x" });
+    expect(get.mock.calls[0]?.[1]?.getQueryString()).toContain("include=uid");
+  });
+
+  it("fetches the bundle-scoped path for a collection when no seededDoc is given", async () => {
+    const c = client();
+    const router = createRouter({ registry: buildRegistry([]), client: c, viewMode: "default" });
+    await router.navigate("entity.collection", { type: "node", bundle: "article" });
+    expect(c.get).toHaveBeenCalledWith("node/article");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "noEmit": false,
+    "jsx": "react-jsx",
+    "baseUrl": ".",
+    "paths": {
+      "dropsh/plugin": ["../../src/plugin-api.ts"],
+      "@dropsh/plugin-markdown/render": ["../markdown/src/render-md.ts"]
+    }
+  },
+  "include": ["src", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,15 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      "dropsh/plugin": resolve(__dirname, "../../src/plugin-api.ts"),
+      "@dropsh/plugin-markdown/render": resolve(__dirname, "../markdown/src/render-md.ts"),
+    },
+  },
+  test: {
+    include: ["tests/unit/**/*.test.{ts,tsx}"],
+    environment: "node",
+  },
+});