@flowtty/core 1.0.0-alpha.1

package/dist/testing/index.d.ts

@@ -0,0 +1,63 @@
+import { B as Buffer } from '../cells-CaXEx4lH.js';
+import { B as Backend, K as Key } from '../backend-BcB7VR87.js';
+
+declare class TestBackend implements Backend {
+    private readonly cols;
+    private readonly rows;
+    frames: string[];
+    private buffers;
+    private readonly subscribers;
+    constructor(cols?: number, rows?: number);
+    size(): {
+        width: number;
+        height: number;
+    };
+    draw(buffer: Buffer): void;
+    get lastFrame(): string;
+    get lastBuffer(): Buffer | null;
+    onKey(handler: (key: Key) => void): () => void;
+    /** Synchronously deliver one Key to every subscriber. */
+    press(key: Partial<Key> & {
+        name: string;
+    }): void;
+    /** Emit one Key per character; printable chars only. */
+    type(text: string): void;
+    dispose(): void;
+}
+
+/**
+ * Resolve after pending microtasks have drained. Use after `backend.press(...)`
+ * to wait for React's state update + the scheduled repaint:
+ *
+ *     backend.press({ name: 'a' });
+ *     await flush();
+ *     expect(backend.lastFrame).toBe('a');
+ */
+declare function flush(): Promise<void>;
+/**
+ * Wait for React scheduler-driven re-renders triggered by `setState` inside
+ * `useEffect` (e.g. a Form field registering, then the group auto-focusing the
+ * first field) to fully commit.
+ *
+ * A passive-effect `setState` lands on React's default lane, which the
+ * production Scheduler only drains on a macrotask — there is no synchronous
+ * escape hatch in react-reconciler. A single `setTimeout(0)` (the old impl)
+ * therefore advances only ONE step of a multi-step effect cascade and can also
+ * lose the race against the Scheduler's own MessageChannel macrotask; both
+ * surface as a stale/empty `lastFrame`.
+ *
+ * Passing the `TestBackend` makes this deterministic: each round yields one
+ * macrotask (draining the Scheduler, which flushes that commit's passive
+ * effects exactly as in production) plus a microtask pair (for the coalesced
+ * repaint), and we stop once two consecutive rounds add no new frame. Two
+ * rounds — not one — so a single macrotask-ordering inversion (Scheduler work
+ * landing just after our `setTimeout`) can't read as premature quiescence.
+ *
+ * Called with no backend it falls back to a single macrotask round (the legacy
+ * behavior) for callers that don't need cascade-settling.
+ */
+declare function flushAsync(backend?: {
+    readonly frames: readonly unknown[];
+}): Promise<void>;
+
+export { TestBackend, flush, flushAsync };

package/dist/testing/index.js

@@ -0,0 +1,72 @@
+// src/testing/test-backend.ts
+var TestBackend = class {
+  constructor(cols = 40, rows = 10) {
+    this.cols = cols;
+    this.rows = rows;
+  }
+  cols;
+  rows;
+  frames = [];
+  buffers = [];
+  subscribers = /* @__PURE__ */ new Set();
+  size() {
+    return { width: this.cols, height: this.rows };
+  }
+  draw(buffer) {
+    this.frames.push(buffer.toString());
+    this.buffers.push(buffer);
+  }
+  get lastFrame() {
+    return this.frames[this.frames.length - 1] ?? "";
+  }
+  get lastBuffer() {
+    return this.buffers[this.buffers.length - 1] ?? null;
+  }
+  onKey(handler) {
+    this.subscribers.add(handler);
+    return () => {
+      this.subscribers.delete(handler);
+    };
+  }
+  /** Synchronously deliver one Key to every subscriber. */
+  press(key) {
+    const k = {
+      sequence: key.sequence ?? "",
+      ctrl: key.ctrl ?? false,
+      meta: key.meta ?? false,
+      shift: key.shift ?? false,
+      name: key.name
+    };
+    for (const h of [...this.subscribers]) h(k);
+  }
+  /** Emit one Key per character; printable chars only. */
+  type(text) {
+    for (const ch of text) this.press({ name: ch, sequence: ch });
+  }
+  // eslint-disable-next-line @typescript-eslint/no-empty-function
+  dispose() {
+  }
+};
+
+// src/testing/index.ts
+async function flush() {
+  await Promise.resolve();
+  await Promise.resolve();
+}
+async function flushAsync(backend) {
+  if (!backend) {
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    return;
+  }
+  const MAX_ROUNDS = 20;
+  let stableRounds = 0;
+  for (let i = 0; i < MAX_ROUNDS && stableRounds < 2; i++) {
+    const before = backend.frames.length;
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    await Promise.resolve();
+    await Promise.resolve();
+    stableRounds = backend.frames.length === before ? stableRounds + 1 : 0;
+  }
+}
+
+export { TestBackend, flush, flushAsync };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@flowtty/core",
+  "version": "1.0.0-alpha.1",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mellonis/flowtty.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://github.com/mellonis/flowtty#readme",
+  "bugs": "https://github.com/mellonis/flowtty/issues",
+  "description": "Framework-free core: Buffer, Cell, Style, Key, Backend interface. Every adapter (React, Svelte) and every backend (TTY, Test, Electron) depends on this.",
+  "keywords": [
+    "flowtty",
+    "terminal",
+    "tui",
+    "terminal-ui",
+    "cli",
+    "react-reconciler",
+    "yoga",
+    "flexbox",
+    "ansi",
+    "buffer"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./host": {
+      "types": "./dist/host/index.d.ts",
+      "import": "./dist/host/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yoga-layout": "^3.2.1"
+  },
+  "devDependencies": {
+    "tsup": "^8"
+  }
+}