agentlas 1.0.36 → 1.0.38

package/engine/storm/storm.cjs

@@ -36,7 +36,13 @@ function create(deps) {
   const D = deps;
   const { swarmRun } = require("./swarm.cjs").create(D);
 
+  /*
+   * pi-tui 이행 정지작업 (D3 Phase 1-2, 2026-08-11): ctx가 준 Ui가 있으면 그것을
+   * 쓴다. 자체 생성 Ui는 렌더러 교체 시 구 코드가 stdout에 직접 써 프레임을
+   * 찢는 병렬 경로였다. 생성은 주입이 없을 때의 폴백으로만 남긴다.
+   */
   function newUi(lang) {
+    if (D.uiInstance) return D.uiInstance;
     return new Ui({ lang: lang || D.prefsLang() });
   }
 
@@ -78,7 +84,7 @@ function create(deps) {
       return { ok: false };
     }
     if (goal.startsWith("-")) {
-      ui.error("goal cannot start with '-'.");
+      ui.error("goal cannot start with '-'.", { reveal: true });
       return { ok: false };
     }
     const cwd = ctx.cwd || (typeof D.projectCwd === "function" ? D.projectCwd() : D.runCwd());
@@ -86,7 +92,7 @@ function create(deps) {
     try {
       executionHarness = await loadCoreStormbreakerHarness(cwd);
     } catch (error) {
-      ui.error(`Stormbreaker Core harness unavailable: ${String((error && error.message) || error).slice(0, 400)}`);
+      ui.error(`Stormbreaker Core harness unavailable: ${String((error && error.message) || error).slice(0, 400)}`, { reveal: true });
       return { ok: false, error: "stormbreaker-core-harness-unavailable" };
     }
     const args = ["route", goal, "--project", cwd, "--runtime", "terminal"];

package/engine/storm/swarm.cjs

@@ -127,7 +127,13 @@ function parseSwarmOutput(text) {
 function create(deps) {
   const D = deps;
 
+  /*
+   * pi-tui 이행 정지작업 (D3 Phase 1-2, 2026-08-11): ctx가 준 Ui가 있으면 그것을
+   * 쓴다. 자체 생성 Ui는 렌더러 교체 시 구 코드가 stdout에 직접 써 프레임을
+   * 찢는 병렬 경로였다. 생성은 주입이 없을 때의 폴백으로만 남긴다.
+   */
   function newUi(lang) {
+    if (D.uiInstance) return D.uiInstance;
     return new Ui({ lang: lang || D.prefsLang() });
   }
 
@@ -146,7 +152,7 @@ function create(deps) {
     // Core 하네스 없이 stormbreaker 모드 진입 금지 — 로컬 모조 프롬프트로 대체하는
     // 것은 계약 위반이다(모델 실행 전에 실패해야 한다).
     if (stormbreaker && (!executionHarness || typeof executionHarness.system_prompt !== "string")) {
-      ui.error("Stormbreaker requires the canonical Goal + UltraCode harness from Agentlas Core.");
+      ui.error("Stormbreaker requires the canonical Goal + UltraCode harness from Agentlas Core.", { reveal: true });
       return { ok: false, error: "stormbreaker-core-harness-unavailable" };
     }
     const coreHarnessPrompt = executionHarness && executionHarness.system_prompt;
@@ -307,7 +313,7 @@ function create(deps) {
     if (!planned) {
       ui.error(ui.lang === "ko"
         ? "플래너가 유효한 실행 계획(JSON)을 내지 못했습니다 — 정지합니다 (조용한 폴백 금지)."
-        : "The planner did not produce a valid plan JSON — stopping (no silent fallback).");
+        : "The planner did not produce a valid plan JSON — stopping (no silent fallback).", { reveal: true });
       return { ok: false, reason: "invalid_plan_json" };
     }
     if (planned) {
@@ -376,7 +382,7 @@ function create(deps) {
     ui.line("");
     ui.info(`tasks: ${tasks.length}  ·  done: ${done.length}  ·  failed: ${failed}`);
     if (!done.length) {
-      ui.error(ui.lang === "ko" ? "스웜이 완료한 작업이 없습니다." : "The swarm completed no work.");
+      ui.error(ui.lang === "ko" ? "스웜이 완료한 작업이 없습니다." : "The swarm completed no work.", { reveal: true });
       return { ok: false };
     }
 
@@ -411,7 +417,7 @@ function create(deps) {
       );
     } catch (e) {
       ui.stopSpinner();
-      ui.error("Synthesis failed: " + String((e && e.message) || e).slice(0, 200));
+      ui.error("Synthesis failed: " + String((e && e.message) || e).slice(0, 200), { reveal: true });
       finalText = pieces;
     }
     ui.stopSpinner();
@@ -435,7 +441,7 @@ function create(deps) {
     const strayFlag = rest.find((token) => String(token).startsWith("-"));
     if (strayFlag) {
       const ui = executionContext.ui || newUi();
-      ui.error(`unknown option ${strayFlag} — swarm accepts: --parallel N | -n N, --runtime <kind>`);
+      ui.error(`unknown option ${strayFlag} — swarm accepts: --parallel N | -n N, --runtime <kind>`, { reveal: true });
       process.exitCode = 1;
       return { ok: false, error: "unknown-option" };
     }

package/engine/ui/pitui-shell.cjs

@@ -0,0 +1,295 @@
+"use strict";
+/*
+ * ui/pitui-shell — pi-tui 기반 실험 셸 (D3 Phase 2 증분 1, 2026-08-11).
+ *
+ * 켜는 법: AGENTLAS_TUI=pi agentlas   (TTY 필수 · 기본 REPL은 그대로 정본)
+ *
+ * 설계 (D2 위험 5의 해법이 이 파일의 구조다):
+ *  - PiUi 는 기존 Ui 를 상속하되 write() 초크포인트만 pi-tui 트랜스크립트로 돌린다.
+ *    line/_message/tool/rule 등 기존 메서드는 전부 write 로 수렴하므로 그대로 산다.
+ *  - 스트리밍 3종은 Markdown 누적으로 교체 — 표·코드블록이 실시간 재렌더된다.
+ *  - 스피너는 pi-tui Loader 로 교체 (기존 \r 기반 페인트는 dummy 스트림으로 무해화).
+ *  - ctx.out/err 55파일의 직출력은 shellCtx 재지정으로 전부 프레임 안에 들어온다.
+ *  - 자동완성은 ui/palette 정본(SLASH_COMMANDS)을 pi-tui SlashCommand 로 변환 — 목록 드리프트 금지.
+ *
+ * 증분 1 범위 밖(기본 REPL로): Shift-Tab 권한 순환 · ! 셸 · 세션 전환(/s) ·
+ * 히스토리 디스크 영속 · 스티어링 큐 표시. 이 항목들은 D3 Phase 2-2에서 이전한다.
+ */
+const { PassThrough } = require("node:stream");
+const { Ui } = require("../agentlas-ui.cjs");
+const { Orchestrator, maxParallel } = require("../sessions/orchestrator.cjs");
+const { Renderer } = require("./renderer.cjs");
+const { resolveRuntimeForAgent } = require("../runtimes/overrides.cjs");
+const permissions = require("../agentlas-permissions.cjs");
+const palette = require("./palette.cjs");
+const { readVersion } = require("../agentlas-banner.cjs");
+const { resolveProjectController, withProjectControllerContext } = require("../project/controller.cjs");
+
+function loadPiTui() {
+  try {
+    // ESM 패키지 — Node >=20.19 의 require(esm). engines 가 이 최소선을 선언한다.
+    return require("@earendil-works/pi-tui");
+  } catch (cause) {
+    throw Object.assign(
+      new Error("pi-tui shell needs Node >=20.19 (require(esm)). Run without AGENTLAS_TUI=pi, or upgrade Node."),
+      { code: "pitui_unavailable", cause },
+    );
+  }
+}
+
+/* Ui 를 상속해 write 초크포인트만 pi-tui 로 돌린다. */
+class PiUi extends Ui {
+  constructor(opts, pi, tui, transcript) {
+    // 실터미널 대신 dummy 스트림 — 놓친 직접 out.write 가 프레임을 찢는 대신 소멸한다.
+    super({ ...opts, stream: new PassThrough(), color: true });
+    this._pi = pi;
+    this._tui = tui;
+    this._transcript = transcript;
+    this._lineBuf = "";
+    this._md = null;      // 스트리밍 중 Markdown 누적 컴포넌트
+    this._mdText = "";
+    this._loader = null;
+  }
+  _appendText(text) {
+    this._transcript.addChild(new this._pi.Text(String(text), 1, 0));
+    this._tui.requestRender();
+  }
+  write(s) {
+    // line()/tool()/rule()/_message() 전부 여기로 수렴한다.
+    this._lineBuf += String(s);
+    let idx;
+    while ((idx = this._lineBuf.indexOf("\n")) !== -1) {
+      this._appendText(this._lineBuf.slice(0, idx));
+      this._lineBuf = this._lineBuf.slice(idx + 1);
+    }
+    this._atLineStart = this._lineBuf === "";
+  }
+  ensureNl() {
+    if (this._lineBuf) { this._appendText(this._lineBuf); this._lineBuf = ""; }
+    this._atLineStart = true;
+  }
+  // ── 스피너 → Loader ──
+  updateSpinner(text) {
+    this._spinText = String(text || this._spinText || "");
+    if (!this._loader) {
+      this._loader = new this._pi.Loader(this._tui, this.c.emerald, this.c.dim, this._spinText);
+      this._transcript.addChild(this._loader);
+    } else {
+      this._loader.setMessage(this._spinText);
+    }
+    this._tui.requestRender();
+  }
+  stopSpinner() {
+    if (this._loader) {
+      this._loader.stop();
+      this._transcript.removeChild(this._loader);
+      this._loader = null;
+      this._tui.requestRender();
+    }
+    this._spinText = "";
+  }
+  // ── 스트리밍 → Markdown 누적 (표·코드블록 실시간 재렌더) ──
+  streamStart() {
+    this.stopSpinner();
+    this.ensureNl();
+    this._mdText = "";
+    this._md = new this._pi.Markdown("", 3, 0, this._mdTheme());
+    this._transcript.addChild(this._md);
+    this._streaming = true;
+  }
+  streamDelta(text) {
+    if (!text) return;
+    if (!this._md) this.streamStart();
+    this._mdText += String(text);
+    /*
+     * Memory Events 봉투는 런타임 계약(펜스 파이프라인이 수확)이지 사용자용이 아니다.
+     * append-only 기본 REPL은 이미 찍힌 봉투를 지울 수 없지만, 누적 재렌더는
+     * 표시만 잘라낼 수 있다 — 수확 경로(st.text/fences)는 건드리지 않는다.
+     */
+    const visible = this._mdText.replace(/\n#{1,3} Memory Events\b[\s\S]*$/, "\n");
+    this._md.setText(visible);
+    this._tui.requestRender();
+    this._streaming = true;
+  }
+  streamEnd() {
+    this._md = null;
+    this._mdText = "";
+    this._streaming = false;
+  }
+  _mdTheme() {
+    const c = this.c;
+    return {
+      heading: (s) => c.bold(c.emerald(s)), link: c.blue, linkUrl: c.dim,
+      code: c.amber, codeBlock: c.green, codeBlockBorder: c.faint,
+      quote: c.dim, quoteBorder: c.faint, hr: c.faint, listBullet: c.emerald,
+      bold: c.bold, italic: c.italic, strikethrough: c.dim, underline: c.underline,
+    };
+  }
+}
+
+function toSlashCommands(lang) {
+  // 팔레트 정본 → pi-tui SlashCommand. "/" 접두는 pi-tui 가 관리하므로 벗긴다.
+  return palette.SLASH_COMMANDS.map((cmd) => ({
+    name: cmd.command.slice(1),
+    description: lang === "ko" ? cmd.ko : cmd.en,
+    argumentHint: cmd.args || undefined,
+  }));
+}
+
+async function startPiShell(ctx, opts = {}) {
+  const pi = loadPiTui();
+  const en = ctx.lang === "en";
+  const db = ctx.db();
+
+  const terminal = new pi.ProcessTerminal();
+  const tui = new pi.TuiMainScreen(terminal);
+  const ui = new PiUi({ lang: ctx.lang }, pi, tui, tui);
+
+  // ctx 초크포인트 재지정 — 55파일의 ctx.out 직출력이 전부 프레임 안으로 들어온다.
+  const shellCtx = {
+    ...ctx,
+    uiInstance: ui,
+    out: (s = "") => ui.line(String(s)),
+    err: (s = "") => ui.line(ui.c.amber(String(s))),
+  };
+
+  const orch = new Orchestrator({ db, lang: ctx.lang });
+  const renderer = new Renderer(ui);
+  let permission = permissions.normalize(opts.permission || (ctx.prefs && ctx.prefs.permission) || "write");
+
+  const resolveRt = (agentId = null) => resolveRuntimeForAgent({
+    db, prefs: ctx.prefs, explicit: opts.runtime || null,
+    model: opts.model || null, effort: opts.effort || null,
+    role: "orchestrator", agentId,
+  });
+  const pickController = () => {
+    const resolved = resolveProjectController(db, process.cwd());
+    return withProjectControllerContext(resolved.controller, resolved.project);
+  };
+  const ensureMainSession = () => {
+    const agent = orch.active() ? orch.active().agent : pickController();
+    if (!agent) {
+      throw Object.assign(new Error(en
+        ? "This project has no available controller — connect with: agentlas project use <agent>"
+        : "이 프로젝트에 실행 가능한 컨트롤러가 없습니다 — agentlas project use <에이전트>로 연결하세요"),
+        { code: "project_not_connected", honestStop: true });
+    }
+    const active = orch.active();
+    if (active && active.agent.id === agent.id) return active;
+    const session = orch.spawn({
+      agent, runtime: resolveRt(agent.id), permission,
+      cwd: process.cwd(), activate: true, chatId: opts.chatId || null,
+    });
+    renderer.attach(session, { replay: false });
+    return session;
+  };
+
+  // ── 헤더 ──
+  ui.line(`${ui.c.paw("▞▖")} ${ui.c.bold("AGENTLAS")} ${ui.c.dim(`${readVersion()} · pi-tui shell (experimental) · parallel ≤${maxParallel()}`)}`);
+  ui.line(ui.c.dim(en
+    ? "plain words run a task · / commands · Esc interrupts · Ctrl+C quits"
+    : "문장을 치면 실행 · / 명령 · Esc 중단 · Ctrl+C 종료"));
+  ui.line("");
+
+  // ── 입력면 ──
+  const editorTheme = {
+    borderColor: ui.c.faint,
+    selectList: {
+      selectedPrefix: ui.c.emerald, selectedText: ui.c.bold,
+      description: ui.c.dim, scrollInfo: ui.c.faint, noMatch: ui.c.dim,
+    },
+  };
+  const editor = new pi.Editor(tui, editorTheme, { autocompleteMaxVisible: 8 });
+  editor.setAutocompleteProvider(new pi.CombinedAutocompleteProvider(toSlashCommands(ctx.lang), process.cwd()));
+
+  const commands = require("../commands/index.cjs");
+  const handleSlash = async (cmdline) => {
+    const raw = cmdline.split(/\s+/)[0] || "";
+    const rest = cmdline.slice(raw.length).trim().split(/\s+/).filter(Boolean);
+    const cmd = commands.resolveCommandName(raw);
+    if (cmd === "quit" || cmd === "exit") return "quit";
+    if (cmd === "help") {
+      ui.line(palette.renderPalette(ctx.lang));
+      return;
+    }
+    const EXCLUDED = new Set(["firm", "setup", "run"]);
+    if (!EXCLUDED.has(cmd) && commands.COMMANDS[cmd]) {
+      await commands.COMMANDS[cmd]().run(shellCtx, rest);
+      return;
+    }
+    if (commands.DESKTOP_ONLY_SURFACES && commands.DESKTOP_ONLY_SURFACES[cmd]) {
+      ui.line(ui.c.dim(commands.DESKTOP_ONLY_SURFACES[cmd]));
+      return;
+    }
+    ui.line(ui.c.dim(en ? `not in the pi shell yet: /${cmd} — use the classic REPL` : `pi 셸에는 아직 없음: /${cmd} — 기본 REPL을 쓰세요`));
+  };
+
+  let busy = false;
+  editor.onSubmit = (text) => {
+    const input = String(text || "").trim();
+    if (!input) return;
+    editor.addToHistory(input);
+    editor.setText("");
+    ui.ensureNl();
+    ui.line(ui.c.emerald("› ") + ui.c.text(input));
+    (async () => {
+      if (input.startsWith("/")) {
+        const verdict = await handleSlash(input.slice(1)).catch((e) => {
+          if (e && (e.code || e.honestStop)) ui.error(e);
+          else ui.error();
+          return null;
+        });
+        if (verdict === "quit") shutdown(0);
+        return;
+      }
+      if (busy) { orch.active()?.send(input).catch(() => {}); return; } // 스티어링 큐
+      busy = true;
+      try {
+        const session = ensureMainSession();
+        await orch.sendTo(session.key, input);
+      } catch (e) {
+        if (e && (e.code || e.honestStop)) ui.error(e);
+        else ui.error();
+      } finally {
+        busy = false;
+      }
+    })();
+  };
+  tui.addChild(editor);
+  tui.setFocus(editor);
+
+  const shutdown = (code) => {
+    try { renderer.detach(); } catch { /* 종료 경로 */ }
+    try { tui.stop(); } catch { /* 종료 경로 */ }
+    Promise.resolve(orch.shutdown && orch.shutdown()).finally(() => process.exit(code));
+  };
+
+  tui.addInputListener((data) => {
+    if (pi.matchesKey(data, "ctrl+c")) {
+      const active = orch.active();
+      if (active && active.isBusy()) {
+        active.kill();
+        ui.ensureNl();
+        ui.line(ui.c.dim(en ? "(turn interrupted)" : "(턴 중단됨)"));
+        return { handled: true };
+      }
+      shutdown(0);
+      return { handled: true };
+    }
+    if (pi.matchesKey(data, "escape")) {
+      const active = orch.active();
+      if (active && active.isBusy()) {
+        active.kill();
+        ui.ensureNl();
+        ui.line(ui.c.dim(en ? "(turn interrupted — Esc)" : "(턴 중단됨 — Esc)"));
+        return { handled: true };
+      }
+    }
+  });
+
+  tui.start();
+  // pi-tui 가 프로세스를 잡고 있는 동안 살아 있는 프라미스
+  return new Promise(() => {});
+}
+
+module.exports = { startPiShell };

package/engine/ui/repl.cjs

@@ -86,6 +86,14 @@ function pickProjectController(db, cwd = process.cwd()) {
 }
 
 async function startRepl(ctx, opts = {}) {
+  /*
+   * 실험 셸 opt-in (D3 Phase 2 증분 1): AGENTLAS_TUI=pi + TTY 일 때만.
+   * 기본 REPL 이 정본이며, 온보딩 전(prefs.onboarded=false)에는 켜지 않는다 —
+   * 마법사는 아직 readline 계약이다(Phase 2-2 에서 이전).
+   */
+  if (process.env.AGENTLAS_TUI === "pi" && process.stdin.isTTY && ctx.prefs && ctx.prefs.onboarded) {
+    return require("./pitui-shell.cjs").startPiShell(ctx, opts);
+  }
   // 마법사가 언어를 바꾸면 이 뒤의 문구도 따라가야 한다 — 아래 온보딩 블록에서 갱신한다.
   let en = ctx.lang === "en";
   const ui = ctx.uiInstance;
@@ -140,6 +148,11 @@ async function startRepl(ctx, opts = {}) {
      * 그대로 보여주고, 어떻게 실행하는지까지 덧붙인다. One 복구는 예상 못 한
      * 실패에만 쓴다. (사람용 문장과 기계 판단은 다른 필드 — 스케줄러와 같은 원칙.)
      */
+    if (error && error.code === "usage") {
+      // 사용법은 복구 대상이 아니라 안내다 — 그대로 보여주고 끝낸다.
+      ui.line(ui.c.dim(String(error.message || error)));
+      return;
+    }
     if (error && (error.honestStop || error.code)) {
       // 공유 controller 모듈은 lang을 모른다 — 기계 code로 여기서 현지화한다.
       const KO_REASON = {
@@ -290,7 +303,7 @@ async function startRepl(ctx, opts = {}) {
      * 눌리는 순간 커서-뒤 지우기(CSI K)로 걷어내므로 readline 의 echo·팔레트
      * 오버레이와 겹치지 않는다. 비TTY·바쁜 세션에서는 그리지 않는다.
      */
-    const { visWidth } = require("../agentlas-composer.cjs");
+    const { visWidth } = require("./width.cjs");
     const GHOST_HINT = en
       ? "type a task · / commands · @ files · ? shortcuts"
       : "할 일을 문장으로 · / 명령 · @ 파일 · ? 단축키";
@@ -628,9 +641,18 @@ function printSessions(ctx, orch) {
  * 날 TypeError 를 냈다. 팔레트가 `/steer <n> <msg>` 라고 안내하므로 인자 없이 Enter 를
  * 눌러 사용법을 보려는 것은 정상적인 탐색이다.
  */
+/*
+ * 사용법 에러는 기계 코드를 단다 — 코드 없는 Error 는 recoverPresentation 이
+ * "One이 복구 중" 으로 치환해 사용법이 통째로 사라졌다(2026-08-11 존폐 판단 결함 2:
+ * /runtime /model /effort /permission /s /switch /kill /rm 여덟 명령).
+ */
+function usageError(text) {
+  return Object.assign(new Error(text), { code: "usage", honestStop: true });
+}
+
 function sessionKeyArg(rest, usage) {
   const token = rest[0];
-  if (!token) throw new Error(usage);
+  if (!token) throw usageError(usage);
   return String(token).startsWith("s") ? token : `s${token}`;
 }
 
@@ -669,7 +691,8 @@ function handleSlash(ctx, cmdline, api) {
       return;
     }
     case "agents": case "list": require("../commands/list.cjs").run(ctx, rest); return;
-    case "doctor": require("../commands/doctor.cjs").run(ctx, rest); return;
+    // doctor 는 세션 검증(네트워크)으로 async 가 됐다 — 특례로 fire-and-forget 하면
+    // REPL 종료가 출력을 잘라먹는다. promise 를 track 하는 default 폴스루로 보낸다.
     case "mcp": require("../commands/mcp.cjs").run(ctx, rest); return;
 
     case "sessions": case "tree": printSessions(ctx, orch); return;
@@ -695,7 +718,7 @@ function handleSlash(ctx, cmdline, api) {
     }
 
     case "runtime": {
-      if (!rest[0]) throw new Error("Usage: /runtime claude-code|codex|gemini");
+      if (!rest[0]) throw usageError("Usage: /runtime claude-code|codex|gemini");
       // 세션 오버라이드는 저장되지 않는다 — 고지 없이는 사용자가 영구 설정으로
       // 믿는다(2026-08-05 감사 결함 C). 영구 경로를 같은 줄에서 알려준다.
       api.setRuntime(rest[0]);
@@ -706,7 +729,7 @@ function handleSlash(ctx, cmdline, api) {
     }
     case "model": {
       const model = String(rest[0] || "").trim();
-      if (!model) throw new Error("Usage: /model <provider-model-id|default>");
+      if (!model) throw usageError("Usage: /model <provider-model-id|default>");
       const next = ["default", "inherit"].includes(model.toLowerCase()) ? null : model;
       api.setModel(next);
       ctx.out(ui.c.dim(
@@ -719,7 +742,7 @@ function handleSlash(ctx, cmdline, api) {
     case "effort": {
       const effort = String(rest[0] || "").trim().toLowerCase();
       if (!EFFORTS.includes(effort)) {
-        throw new Error(`Usage: /effort ${EFFORTS.join("|")}`);
+        throw usageError(`Usage: /effort ${EFFORTS.join("|")}`);
       }
       api.setEffort(effort === "none" ? null : effort);
       ctx.out(ui.c.dim(
@@ -729,7 +752,7 @@ function handleSlash(ctx, cmdline, api) {
     }
     case "permission": {
       if (!["read", "write", "full"].includes(String(rest[0] || ""))) {
-        throw new Error("Usage: /permission read|write|full");
+        throw usageError("Usage: /permission read|write|full");
       }
       const level = permissions.normalize(rest[0]);
       api.setPermission(level);

package/engine/ui/width.cjs

@@ -0,0 +1,172 @@
+"use strict";
+/*
+ * ui/width: 터미널 셀 폭·그래핌 유틸 정본.
+ * agentlas-composer.cjs(데드코드가 된 바텀 입력 박스)에서 2026-08-11 추출 — 함수는
+ * 바이트 동일. 소비자: agentlas-ui / agentlas-banner / agentlas-onboard /
+ * ui/repl / hephaestus/runtime. pi-tui 이행(D3 Phase 1-3) 정지작업.
+ */
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const MARK_RE = /\p{Mark}/u;
+const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
+
+// East-Asian width: CJK / Hangul / Kana / fullwidth glyphs occupy 2 terminal cells.
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals … symbols
+    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana … CJK compat
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK unified
+    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compat forms
+    (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) // emoji / pictographs
+  );
+}
+function charWidth(ch) {
+  const cp = ch.codePointAt(0);
+  if (cp < 0x20) return 0;
+  if (
+    cp === 0x200d || // zero-width joiner
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+    (cp >= 0xe0100 && cp <= 0xe01ef) ||
+    (cp >= 0x1f3fb && cp <= 0x1f3ff) || // emoji skin tones
+    MARK_RE.test(ch)
+  ) return 0;
+  return isWide(cp) ? 2 : 1;
+}
+function graphemeSegments(value) {
+  return [...GRAPHEME_SEGMENTER.segment(String(value || ""))];
+}
+function graphemeWidth(segment) {
+  const text = String(segment || "");
+  if (
+    EXTENDED_PICTOGRAPHIC_RE.test(text) ||
+    /[\u{1f1e6}-\u{1f1ff}]/u.test(text) ||
+    text.includes("\u20e3")
+  ) return 2;
+  let width = 0;
+  for (const ch of text) width += charWidth(ch);
+  return width;
+}
+function previousGraphemeIndex(value, index) {
+  const text = String(value || "");
+  const cursor = Math.max(0, Math.min(Number(index) || 0, text.length));
+  let previous = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const end = entry.index + entry.segment.length;
+    if (cursor <= entry.index) return previous;
+    if (cursor <= end) return entry.index;
+    previous = entry.index;
+  }
+  return previous;
+}
+function nextGraphemeIndex(value, index) {
+  const text = String(value || "");
+  const cursor = Math.max(0, Math.min(Number(index) || 0, text.length));
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const end = entry.index + entry.segment.length;
+    if (cursor < end) return end;
+  }
+  return text.length;
+}
+function visWidth(s) {
+  const clean = String(s).replace(/\x1b\[[0-9;]*m/g, "");
+  let n = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(clean)) n += graphemeWidth(entry.segment);
+  return n;
+}
+
+function truncateWidth(value, max) {
+  const text = String(value || "");
+  if (visWidth(text) <= max) return text;
+  let out = "";
+  let width = 0;
+  const room = Math.max(0, max - 1);
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const cells = graphemeWidth(entry.segment);
+    if (width + cells > room) break;
+    out += entry.segment;
+    width += cells;
+  }
+  return out + "…";
+}
+
+function splitWidth(value, max) {
+  const text = String(value || "");
+  const limit = Math.max(1, Math.floor(Number(max) || 1));
+  const lines = [];
+  let line = "";
+  let width = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const cells = graphemeWidth(entry.segment);
+    if (line && width + cells > limit) {
+      lines.push(line);
+      line = "";
+      width = 0;
+    }
+    line += entry.segment;
+    width += cells;
+  }
+  if (line || !lines.length) lines.push(line);
+  return lines;
+}
+
+function wrapWidth(value, max) {
+  const limit = Math.max(2, Math.floor(Number(max) || 2));
+  const lines = [];
+  const pushWord = (word, state) => {
+    if (!word) return;
+    const cells = visWidth(word);
+    if (state.line && state.width + 1 + cells <= limit) {
+      state.line += " " + word;
+      state.width += 1 + cells;
+      return;
+    }
+    if (state.line) {
+      lines.push(state.line);
+      state.line = "";
+      state.width = 0;
+    }
+    if (cells <= limit) {
+      state.line = word;
+      state.width = cells;
+      return;
+    }
+    let chunk = "";
+    let chunkWidth = 0;
+    for (const entry of GRAPHEME_SEGMENTER.segment(word)) {
+      const width = graphemeWidth(entry.segment);
+      if (chunk && chunkWidth + width > limit) {
+        lines.push(chunk);
+        chunk = "";
+        chunkWidth = 0;
+      }
+      chunk += entry.segment;
+      chunkWidth += width;
+    }
+    state.line = chunk;
+    state.width = chunkWidth;
+  };
+  const paragraphs = String(value || "").split(/\r?\n/);
+  paragraphs.forEach((paragraph) => {
+    const state = { line: "", width: 0 };
+    for (const word of paragraph.trim().split(/\s+/u).filter(Boolean)) pushWord(word, state);
+    if (state.line) lines.push(state.line);
+    else if (!paragraph.trim()) lines.push("");
+  });
+  return lines.length ? lines : [""];
+}
+
+
+module.exports = {
+  visWidth,
+  truncateWidth,
+  splitWidth,
+  wrapWidth,
+  previousGraphemeIndex,
+  nextGraphemeIndex,
+};