@litfamily/litopencode 1.0.17 → 1.0.19

package/dist/tui.js

@@ -0,0 +1,317 @@
+import { createEffect, createMemo, createSignal } from "solid-js";
+import { useTerminalDimensions } from "@opentui/solid";
+import { jsx } from "@opentui/solid/jsx-runtime";
+import { buildMissionView, lastMission, leadingNotice, missionNotices } from "./tui/mission-model.js";
+import { idleMotion, motionTiming, planMotion, sampleMotion } from "./tui/mission-motion.js";
+import { chipBudget, chipLine, homeLine, missionPanel, paletteFromTheme, panelWidth } from "./tui/mission-text.js";
+import { createLedgerReader, missionProjectRoot, readMissionInput } from "./tui/mission-source.js";
+import { bandCard, bandRibbon, readBandOptions } from "./tui/mission-band.js";
+export const litOpenCodeTuiPluginId = "litopencode";
+const homeLineWidth = 69;
+const refreshDelayMs = 80;
+const ledgerPollMs = 2000;
+const toastMs = 4000;
+const trackedSessionLimit = 4;
+const refreshEvents = [
+    "message.updated",
+    "message.part.updated",
+    "todo.updated",
+    "session.status",
+    "session.idle",
+    "session.error",
+    "permission.asked",
+    "permission.replied",
+    "question.asked",
+    "question.replied",
+    "question.rejected"
+];
+function spanFor(segment) {
+    return jsx("span", {
+        style: { fg: segment.fg, ...(segment.bg === undefined ? {} : { bg: segment.bg }), ...(segment.bold === true ? { bold: true } : {}) },
+        children: segment.text
+    });
+}
+function lineElement(line) {
+    return jsx("text", { wrapMode: "none", children: line.length === 0 ? " " : line.map(spanFor) });
+}
+const tui = async (api, options) => {
+    const motionEnabled = options?.motion !== false;
+    const band = readBandOptions(options);
+    const readLedger = createLedgerReader();
+    const sessions = new Map();
+    const tracked = [];
+    const [revision, setRevision] = createSignal(0);
+    const [clock, setClock] = createSignal(Date.now());
+    let frameTimer;
+    let refreshTimer;
+    let pollTimer;
+    const state = () => api.state;
+    const palette = () => paletteFromTheme(api.theme.current, api.theme.mode());
+    // OpenCode keeps the sidebar choice in its KV store under "sidebar" ("auto" or "hide"); a child
+    // session never shows the sidebar. Before the store is ready the setting is unknown.
+    function sidebarSetting() {
+        if (!api.kv.ready)
+            return undefined;
+        const value = api.kv.get("sidebar", "auto");
+        return typeof value === "string" ? value : undefined;
+    }
+    function isChildSession(sessionID) {
+        const session = api.state.session.get(sessionID);
+        return typeof session?.parentID === "string" && session.parentID !== "";
+    }
+    function anyMoving(now) {
+        for (const entry of sessions.values())
+            if (sampleMotion(entry.motion, now).moving)
+                return true;
+        return false;
+    }
+    // The frame timer runs only while a track is moving; an idle session draws nothing new.
+    function ensureFrames() {
+        if (frameTimer !== undefined || !anyMoving(Date.now()))
+            return;
+        frameTimer = setInterval(() => {
+            const now = Date.now();
+            setClock(now);
+            if (!anyMoving(now)) {
+                clearInterval(frameTimer);
+                frameTimer = undefined;
+            }
+        }, motionTiming.frameMs);
+    }
+    function refresh(sessionID) {
+        const now = Date.now();
+        const source = state();
+        const ledger = readLedger(missionProjectRoot(source.path));
+        const next = buildMissionView(readMissionInput(source, sessionID, ledger, now));
+        const entry = sessions.get(sessionID);
+        if (entry !== undefined && JSON.stringify(entry.view) === JSON.stringify(next))
+            return;
+        if (entry !== undefined) {
+            const notice = leadingNotice(missionNotices(entry.view, next));
+            if (notice !== undefined)
+                api.ui.toast({ variant: notice.variant, title: notice.title, message: notice.message, duration: toastMs });
+        }
+        sessions.set(sessionID, { view: next, motion: planMotion(entry?.view, next, now, entry?.motion ?? idleMotion, motionEnabled) });
+        setClock(now);
+        setRevision(revision() + 1);
+        ensureFrames();
+    }
+    function refreshTracked() {
+        refreshTimer = undefined;
+        for (const sessionID of tracked)
+            refresh(sessionID);
+        syncPoll();
+    }
+    // Ledger writes from a terminal or another session fire no TUI event, so an active mission
+    // re-reads goals.json (one lstat while unchanged) every two seconds. Idle sessions do not poll.
+    function syncPoll() {
+        const active = [...sessions.values()].some((entry) => entry.view.active);
+        if (active && pollTimer === undefined)
+            pollTimer = setInterval(refreshTracked, ledgerPollMs);
+        if (!active && pollTimer !== undefined) {
+            clearInterval(pollTimer);
+            pollTimer = undefined;
+        }
+    }
+    function scheduleRefresh() {
+        if (refreshTimer === undefined)
+            refreshTimer = setTimeout(refreshTracked, refreshDelayMs);
+    }
+    function track(sessionID) {
+        if (tracked.includes(sessionID))
+            return;
+        tracked.push(sessionID);
+        if (tracked.length > trackedSessionLimit)
+            sessions.delete(tracked.shift() ?? "");
+        queueMicrotask(() => {
+            refresh(sessionID);
+            syncPoll();
+        });
+    }
+    // Opening a session loads its messages and parts over HTTP, which fires no bus event. Reading the
+    // reactive store here re-runs this effect as they arrive, so a resumed session lights up too.
+    function watchSession(sessionID) {
+        createEffect(() => {
+            const source = state();
+            for (const message of source.session.messages(sessionID)) {
+                if (message.role === "user")
+                    void source.part(message.id).length;
+            }
+            void source.session.todo(sessionID).length;
+            void source.session.status(sessionID)?.type;
+            scheduleRefresh();
+        });
+    }
+    function sessionView(sessionID) {
+        return () => {
+            revision();
+            const entry = sessions.get(sessionID);
+            if (entry === undefined || !entry.view.active)
+                return undefined;
+            return { view: entry.view, frame: sampleMotion(entry.motion, clock()) };
+        };
+    }
+    for (const type of refreshEvents) {
+        api.event.on(type, scheduleRefresh);
+    }
+    api.lifecycle.onDispose(() => {
+        if (frameTimer !== undefined)
+            clearInterval(frameTimer);
+        if (refreshTimer !== undefined)
+            clearTimeout(refreshTimer);
+        if (pollTimer !== undefined)
+            clearInterval(pollTimer);
+        sessions.clear();
+    });
+    api.slots.register({
+        order: 50,
+        slots: {
+            session_prompt_right(_ctx, props) {
+                track(props.session_id);
+                watchSession(props.session_id);
+                const current = sessionView(props.session_id);
+                const dimensions = useTerminalDimensions();
+                const visible = createMemo(() => current() !== undefined);
+                return () => {
+                    if (!visible())
+                        return null;
+                    return jsx("box", {
+                        flexDirection: "row",
+                        flexShrink: 0,
+                        children: () => {
+                            const snapshot = current();
+                            if (snapshot === undefined)
+                                return null;
+                            const budget = chipBudget({ width: dimensions().width, sidebar: sidebarSetting(), child: isChildSession(props.session_id) });
+                            return lineElement(chipLine(snapshot.view, snapshot.frame, palette(), budget));
+                        }
+                    });
+                };
+            },
+            sidebar_content(_ctx, props) {
+                track(props.session_id);
+                watchSession(props.session_id);
+                const current = sessionView(props.session_id);
+                const panel = createMemo(() => {
+                    const snapshot = current();
+                    return snapshot === undefined ? undefined : missionPanel(snapshot.view, snapshot.frame, palette());
+                });
+                const visible = createMemo(() => panel() !== undefined);
+                return () => {
+                    if (!visible())
+                        return null;
+                    // Props are getters so the border, titles and fill follow each frame without rebuilding the box.
+                    return jsx("box", {
+                        border: true,
+                        borderStyle: "rounded",
+                        width: panelWidth,
+                        flexShrink: 0,
+                        flexDirection: "column",
+                        paddingLeft: 1,
+                        paddingRight: 1,
+                        titleAlignment: "left",
+                        bottomTitleAlignment: "right",
+                        get borderColor() { return panel()?.border; },
+                        get title() { return panel()?.title; },
+                        get titleColor() { return panel()?.titleColor; },
+                        get bottomTitle() { return panel()?.bottomTitle ?? ""; },
+                        get backgroundColor() { return panel()?.background ?? "transparent"; },
+                        children: () => (panel()?.rows ?? []).map(lineElement)
+                    });
+                };
+            }
+        }
+    });
+    // The band: one full-width ribbon row under every route in app_bottom. It follows the session on
+    // screen; a child (subagent) session shows its parent's mission as a lane. Home shows no band.
+    if (band.enabled) {
+        api.slots.register({
+            order: 50,
+            slots: {
+                app_bottom() {
+                    const dimensions = useTerminalDimensions();
+                    const target = createMemo(() => {
+                        const route = api.route.current;
+                        const id = route.name === "session" && typeof route.params?.sessionID === "string" ? route.params.sessionID : undefined;
+                        if (id === undefined)
+                            return undefined;
+                        const parent = api.state.session.get(id)?.parentID;
+                        return typeof parent === "string" && parent !== "" ? { sessionID: parent, inLane: true } : { sessionID: id, inLane: false };
+                    });
+                    createEffect(() => {
+                        const place = target();
+                        if (place === undefined)
+                            return;
+                        track(place.sessionID);
+                        watchSession(place.sessionID);
+                    });
+                    const current = createMemo(() => {
+                        const place = target();
+                        const snapshot = place === undefined ? undefined : sessionView(place.sessionID)();
+                        return snapshot === undefined || place === undefined ? undefined : { ...snapshot, inLane: place.inLane };
+                    });
+                    const visible = createMemo(() => current() !== undefined);
+                    return () => {
+                        if (!visible())
+                            return null;
+                        return jsx("box", {
+                            flexDirection: "column",
+                            flexShrink: 0,
+                            get backgroundColor() { return palette().panel ?? "transparent"; },
+                            children: () => {
+                                const snapshot = current();
+                                if (snapshot === undefined)
+                                    return null;
+                                const colors = palette();
+                                const width = dimensions().width;
+                                const rows = [
+                                    jsx("box", { paddingLeft: 2, paddingRight: 2, flexShrink: 0, children: lineElement(bandRibbon(snapshot.view, snapshot.frame, colors, width - 4, { inLane: snapshot.inLane })) })
+                                ];
+                                const card = band.card ? bandCard(snapshot.view, snapshot.frame, colors, width - 2) : undefined;
+                                if (card !== undefined) {
+                                    rows.push(jsx("box", {
+                                        border: true,
+                                        borderStyle: "rounded",
+                                        borderColor: card.border,
+                                        title: card.title,
+                                        titleColor: colors.text,
+                                        marginLeft: 1,
+                                        marginRight: 1,
+                                        paddingLeft: 1,
+                                        paddingRight: 1,
+                                        flexShrink: 0,
+                                        flexDirection: "column",
+                                        children: card.rows.map(lineElement)
+                                    }));
+                                }
+                                return rows;
+                            }
+                        });
+                    };
+                }
+            }
+        });
+    }
+    // After the built-in home tips (order 100): one line about the project's last mission, if any.
+    api.slots.register({
+        order: 150,
+        slots: {
+            home_bottom() {
+                const dimensions = useTerminalDimensions();
+                const line = createMemo(() => {
+                    revision();
+                    return homeLine(lastMission(readLedger(missionProjectRoot(state().path))), palette(), Math.min(homeLineWidth, dimensions().width - 10));
+                });
+                return () => {
+                    const segments = line();
+                    return segments.length === 0 ? null : jsx("box", { flexDirection: "row", justifyContent: "center", flexShrink: 0, children: lineElement(segments) });
+                };
+            }
+        }
+    });
+};
+const plugin = {
+    id: litOpenCodeTuiPluginId,
+    tui
+};
+export default plugin;

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.17"><title>release: 1.0.17</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.17</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.19"><title>release: 1.0.19</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.19</text></g></svg>

package/docs/reference-Ko-KR.md

@@ -242,6 +242,77 @@ npm uninstall -g @litfamily/litopencode
 프로젝트의 `.litopencode/`는 별도 ledger와 receipt입니다. 나중에 재개할 계획이 없다면
 그 상태를 버려도 되는지 확인한 뒤 직접 정리합니다.
 
+TUI 패널 항목은 `tui.json`이나 `tui.jsonc`에 있습니다. `litopencode tui remove [--root <dir>]`는
+두 파일에서 LitOpenCode 항목만 지우고, 다른 플러그인과 주석은 그대로 둡니다. 바뀌는 파일은 먼저
+`<file>.litopencode-backup`으로 복사합니다. `--dry-run`은 같은 결과를 보여 주기만 하고 아무것도 쓰지 않습니다.
+
+## TUI 미션 패널
+
+OpenCode 1.18은 `tui.json`이나 `tui.jsonc`의 `plugin` 배열에 적힌 TUI 플러그인을 불러옵니다.
+이 패키지는 TUI 모듈을 서버 플러그인과 따로 `@litfamily/litopencode/tui`(`dist/tui.js`, 플러그인 id
+`litopencode`)로 내보냅니다. OpenCode가 두 대상을 한 모듈에 섞는 것을 허용하지 않기 때문입니다.
+
+화면에 그리는 것:
+
+- 입력창 아래 agent/model 줄 오른쪽의 단계 칩: `🔥 LIT` 알약 뒤에 `PLAN` › `WORK n/m` › `REVIEW`
+  알약과 다섯 칸 `▰▱` 막대가 붙습니다. 자리가 좁으면 이름부터 덜어 내서, `🔥`와 지금·다음 단계만,
+  더 좁으면 `🔥`와 개수만 남깁니다. 자리는 OpenCode에 저장된 사이드바 설정과 세션 종류(하위 세션에는
+  사이드바가 없음)로 계산합니다. 설정을 아직 읽을 수 없으면 사이드바가 열려 있다고 보고 좁게 잡습니다.
+- 세션 사이드바 맨 위의 미션 패널: 36칸짜리 둥근 상자이고, 위 테두리에 `🔥 LIT ▸ <단계>`, 아래
+  테두리에 `n/m criteria`가 붙습니다. 테두리 색이 상태를 보여 줍니다. 일하는 중에는 테마 accent,
+  경고가 있으면 warning, 끝나면 success 색입니다. 안에는 두 줄짜리 `LIT`과 그 옆의 작업 이름·상태,
+  굵은 목표 제목, 단계 줄, 1/8칸 블록으로 칠하고 빈 곳은 가는 선으로 둔 그라데이션 막대, 다음 할 일이나
+  아직 통과하지 못한 기준, 기준 목록, 경고, 최근 증거 네 개가 들어갑니다.
+- 띠(band): 화면 맨 아래 전체 폭에 붙는 리본 한 줄입니다(OpenCode의 `app_bottom` 자리). 세션과
+  사이드바 아래를 모두 가로지릅니다. 알약, 1/8칸 막대, 다음 할 일, 첫 lit 턴부터 지난 시간(`⟳ 7m`)을
+  보여 줍니다. 경고가 열려 있는 동안에는 `▸ 다음 일` 자리에 `⚑ <내용>`이 들어갑니다. 세션의 첫 lit
+  턴에 나타나 lit 세션 내내 남으므로, 입력창은 한 번만 움직입니다. 하위(subagent) 세션에서는 부모
+  세션의 미션을 `· in lane`과 함께 보여 주고, 홈 화면에는 띠가 없습니다. 폭이 좁으면 단계 이름,
+  다음 할 일 글자, 막대 길이, 시간 순서로 덜어 내며 줄을 넘기지 않습니다. 완료 순간도 여기서 함께 보입니다.
+- 홈 화면 입력창 아래, OpenCode 팁 다음 줄: `🔥 lit ready · last: <목표> ✓ n/m`. 프로젝트 ledger에
+  목표가 있을 때만 보입니다.
+- 경고는 색만 바꾸지 않고 늘 `⚑`와 글자를 함께 붙입니다. accent와 warning이 같은 색인 테마가 있기
+  때문입니다. 알파가 0인 테마 바탕(system, lucent-orng)은 검게 칠하지 않고 비워 둡니다.
+- 관문 사건마다 토스트 하나: 계획 저장 또는 저장 실패, 목표 설정, 기준 통과, 리뷰 막힘과 해결, 완료.
+  한 번에 여러 사건이 생기면 가장 급한 것 하나로 합칩니다.
+- 목표가 끝나거나 할 일이 모두 끝나면 1.2초 안에 끝나는 완료 순간을 보여 줍니다. 테두리가 초록으로
+  바뀌고 막대가 끝까지 차며, `WORK`와 `REVIEW`가 차례로 완료로 바뀝니다. 브랜드에 빛이 한 번 지나가고,
+  패널 안으로 불씨가 올라가며, `COMPLETE`가 살짝 넘쳤다가 제자리로 옵니다.
+
+데이터는 이미 있는 것만 읽고, TUI를 위해 새로 쓰는 파일은 없습니다.
+
+- `lit`이 모드를 켜거나 명령이 실행될 때(`save-plan` 포함) 이 플러그인이 사용자 메시지 part에 붙이는
+  `metadata.litopencode` 표시. 표시가 없는 세션은 쉬는 상태로 보고, 기본 `lit-loop` agent여도 칩과
+  패널을 숨깁니다.
+- 세션의 OpenCode 할 일 목록(진행도와 다음 항목), 상태(재시도), 대기 중인 권한 요청과 질문, 마지막
+  assistant 메시지 기준 context 사용량(75%부터 주황).
+- 프로젝트 루트의 `.litopencode/litgoal/lit-loop/goals.json`. 심볼릭 링크와 1 MiB가 넘는 파일은 읽지
+  않습니다. 세션의 첫 lit 턴보다 먼저 마지막으로 바뀐 목표는 이전 작업으로 보고 빼 둡니다.
+
+움직임은 전환이 일어나는 동안에만 짧은 프레임 타이머로 돌고 끝나면 멈춥니다. 새 줄과 알약은
+ease-out-back으로 160ms씩, 60ms 간격으로 들어오고, 막대는 300ms에 차오릅니다. 경고 줄은 220ms에
+걸쳐 들어오고 색은 140ms 동안 넘어가며, 빛이 지나가는 데는 400ms가 걸립니다. lit 세션이
+열려 있는 동안만 2초마다 목표 ledger를 다시 읽고, 쉬는 세션은 읽지 않습니다. 색은 지금 OpenCode
+테마에서 가져옵니다. 움직임을 끄려면 `tui.json`에 `["@litfamily/litopencode@<version>", { "motion": false }]`
+처럼 적고, 플러그인 자체를 끄려면 OpenCode 플러그인 관리자나 `plugin_enabled`에서 id `litopencode`를 끕니다.
+
+띠 설정도 같은 옵션 객체에 적습니다.
+
+- `{ "band": false }`는 띠만 없애고 칩, 패널, 홈 줄은 그대로 둡니다.
+- `{ "band": { "card": true } }`는 리본 아래에 경고, 다음 할 일, 목표를 담은 둥근 카드를 붙입니다.
+  목표가 있는 동안 카드는 네 줄로 고정되어, 경고가 생기거나 사라져도 입력창이 움직이지 않습니다.
+  카드는 기본으로 꺼져 있습니다.
+
+다른 터미널에서 쓴 ledger(예: `litopencode record-evidence`)는 OpenCode 이벤트를 만들지 않습니다.
+그래서 2초마다 도는 공용 ledger 확인이 이를 잡고, 칩·패널·띠가 같은 프레임 시계로 함께 바뀝니다.
+
+항목은 install이 씁니다. 기본 root에서는 `opencode plugin`이 `./tui` export를 보고 직접 항목을 넣고,
+LitOpenCode가 중복과 옛 버전을 정리합니다. custom root에서는 LitOpenCode가 직접 씁니다. 이미
+LitOpenCode 항목이 있는 파일을 고치고, 없으면 `tui.json`과 `tui.jsonc` 중 먼저 있는 파일을, 둘 다 없으면
+새 `tui.json`을 씁니다. OpenCode가 고르는 방식과 같습니다. `./herdr-tui-session.js` 같은 다른 항목과
+모든 주석은 그대로 남습니다. `plugin` 목록 안의 주석을 지워야 하는 경우에는 아무것도 쓰기 전에 install을
+멈춥니다. `doctor`는 이 항목을 `install.tui`에 보고하고, `install.ok` 값은 바꾸지 않습니다.
+
 ## 자동 인수인계
 
 자동 인수인계는 직접 켜야 하며 기본은 꺼져 있습니다. 기본 퍼센트는 없습니다. 플러그인의 `event` 훅과 `experimental.chat.system.transform` 훅에서 동작하고, 대화 내용은 읽지 않으며 assistant 메시지의 토큰 수만 봅니다.
@@ -338,7 +409,7 @@ OpenCode는 세션이 바쁜 동안 들어온 `summarize` 호출을 줄 세웠
 
 - 패키지와 plugin id: `litopencode`
 - CLI binary: `litopencode`
-- 공개 export: `litopencode`, `litopencode/server`
+- 공개 export: `litopencode`, `litopencode/server`, `litopencode/tui`
 - 전역 route 파일: `~/.config/opencode/litopencode.json`
 - 프로젝트 override: `.litopencode/config.json`
 - Durable 상태: `.litopencode/litgoal/`

package/docs/reference.md

@@ -342,6 +342,87 @@ OpenCode's managed `opencode.jsonc` (or the custom root's `opencode.json`). Remo
 Project `.litopencode/` state is separate; preserve it for later resume or remove it only
 when discarding that project's ledger and receipts is intentional.
 
+The TUI panel entry lives in `tui.json` or `tui.jsonc`. `litopencode tui remove [--root <dir>]`
+deletes LitOpenCode's own entry from both files, keeps every other plugin and every comment, and
+copies each changed file to `<file>.litopencode-backup` first. `--dry-run` prints the same receipt
+and writes nothing.
+
+## TUI mission panel
+
+OpenCode 1.18 loads TUI plugins listed in the `plugin` array of `tui.json` or `tui.jsonc`. The
+package exports its TUI module as `@litfamily/litopencode/tui` (`dist/tui.js`, plugin id
+`litopencode`), separate from the server plugin, as OpenCode requires.
+
+What it draws:
+
+- A phase chip on the right of the prompt's agent/model row: a `🔥 LIT` pill, then `PLAN` ›
+  `WORK n/m` › `REVIEW` pills and a five-segment `▰▱` bar. When the row is narrower it drops the
+  labels first: `🔥` with the current and next phase, then `🔥` with only the count. The room comes
+  from OpenCode's stored sidebar setting and the session kind (a child session has no sidebar); when
+  the setting cannot be read yet, the chip assumes the sidebar is open and stays narrower.
+- A mission panel at the top of the session sidebar, in a 36-cell rounded box titled
+  `🔥 LIT ▸ <PHASE>` with `n/m criteria` in the bottom border. The border carries the state: the
+  theme accent while working, the warning colour on a warning, the success colour when complete.
+  Inside: a two-row `LIT` with the discipline and a status beside it, the goal title in bold, the
+  phase line, a gradient bar drawn in eighth-cell blocks over a thin rule, the next todo or open
+  criterion, the criteria, warnings, and the last four evidence events.
+- A band: one full-width ribbon row at the bottom of the screen (OpenCode's `app_bottom` slot), under
+  the session and the sidebar alike. It shows the pills, an eighth-block bar, the next task and the
+  time since the first lit turn (`⟳ 7m`). While a warning is open, `⚑ <text>` takes the place of
+  `▸ next`. The row appears at the session's first lit turn and stays for the whole lit session, so
+  the prompt moves only once. A subagent session shows its parent's mission with `· in lane`; the
+  home screen has no band. When the row is narrow it drops, in order, the step labels, the next-task
+  text, bar width and then the time; it never wraps. The completion moment plays here too.
+- A line under the home prompt, after OpenCode's tips: `🔥 lit ready · last: <goal> ✓ n/m`. It
+  appears only when the project ledger holds a goal.
+- Warnings always carry `⚑` and words, not colour alone, because some themes use one colour for
+  both accent and warning. Theme surfaces with alpha 0 (the system and lucent-orng themes) are left
+  unfilled rather than painted black.
+- One toast per refresh for a gate event: plan saved or not saved, goal set, criterion passed,
+  review blocker opened or resolved, and completion. Several events at once collapse into the most
+  urgent one.
+- A completion moment of at most 1.2 seconds when the goal completes or every todo is done: the
+  border turns green, the bar fills, `WORK` then `REVIEW` turn done, a light sweep crosses the brand,
+  embers rise through the panel and `COMPLETE` pops in with a small overshoot before it settles.
+
+Where the data comes from, with nothing new written for the TUI:
+
+- The `metadata.litopencode` marks this plugin already attaches to user-message parts when `lit`
+  activates a mode or a command runs (`save-plan` included). A session with no mark is idle and the
+  chip and panel stay hidden, even on the default `lit-loop` agent.
+- OpenCode's todo list for the session (progress and next item), its status (retry), pending
+  permissions and questions, and context use from the last assistant message (amber at 75%).
+- `.litopencode/litgoal/lit-loop/goals.json` under the project root. Symbolic links and files over
+  1 MiB are ignored. A goal last updated before the session's first lit turn is treated as earlier
+  work and left out.
+
+Motion runs on a short frame timer only while a transition plays and stops afterwards: new rows
+and pills slide in with ease-out-back, 160 ms each and 60 ms apart; the bar fills in 300 ms; a
+warning row slides in over 220 ms and colours cross-fade in 140 ms; the light sweep takes 400 ms. While a
+lit session is open the panel re-reads the goal ledger every two seconds; an idle session does not.
+Colours come from the active OpenCode theme. Set `["@litfamily/litopencode@<version>", { "motion": false }]`
+in `tui.json` to keep it static, or turn the plugin off by id `litopencode` in OpenCode's plugin
+manager or with `plugin_enabled`.
+
+Band options go in the same options object:
+
+- `{ "band": false }` removes the band and leaves the chip, the panel and the home line.
+- `{ "band": { "card": true } }` adds a rounded card under the ribbon with the warnings, the next
+  task and the goal. While a goal exists the card keeps a fixed four rows, so a warning arriving or
+  clearing never moves the prompt. The card is off by default.
+
+A ledger written from another terminal (for example `litopencode record-evidence`) raises no
+OpenCode event, so the shared two-second ledger check picks it up; the chip, the panel and the band
+then change on the same frame clock.
+
+Install writes the entry. On the default root `opencode plugin` adds it from the `./tui` export and
+LitOpenCode then removes duplicates and stale versions; on a custom root LitOpenCode writes it. The
+file that already holds a LitOpenCode entry is edited, otherwise the first of `tui.json` and
+`tui.jsonc` that exists, otherwise a new `tui.json`, matching OpenCode's own choice. Other entries
+such as `./herdr-tui-session.js` and all comments stay; an edit that would delete a comment inside
+the `plugin` list stops the install before anything is written. `doctor` reports the entry under
+`install.tui` without changing `install.ok`.
+
 ## Automatic handoff
 
 Automatic handoff is opt-in and OFF by default. There is no default percent. It works in the plugin's `event` hook and its `experimental.chat.system.transform` hook, and it reads nothing from the conversation except each assistant message's token counts.
@@ -453,7 +534,7 @@ only. It is sent only in the `Authorization` header and is never written, logged
 
 - Package and plugin id: `litopencode`
 - CLI binary: `litopencode`
-- Public exports: `litopencode` and `litopencode/server`
+- Public exports: `litopencode`, `litopencode/server` and `litopencode/tui`
 - Global route file: `~/.config/opencode/litopencode.json`
 - Project overrides: `.litopencode/config.json`
 - Durable state: `.litopencode/litgoal/`

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@litfamily/litopencode",
-  "version": "1.0.17",
-  "description": "LitOpenCode OpenCode plugin bootstrap package.",
+  "version": "1.0.19",
+  "description": "Workflow plugin for OpenCode: add lit to a prompt and the work is planned, built, checked and written down so the next session can pick it up.",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "ai-agents",
+    "coding-agent",
+    "agent-workflow",
+    "planning",
+    "code-review",
+    "research",
+    "context-handoff",
+    "developer-tools",
+    "korean",
+    "docx",
+    "pptx"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,6 +37,10 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "import": "./dist/server.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
     }
   },
   "scripts": {

package/skills/lit-docx/scripts/docx_design.py

@@ -58,7 +58,7 @@ LABELS = {
 }
 PACK_KEYS = {"schema_version", "tonality", "summary", "dials", "docx", "design"}
 DESIGN_KEYS = {"ramp", "numbering", "h1_rule", "title_block", "contents", "summary_form", "conclusion_first", "running_head", "justify",
-               "palette", "accent_on", "page_geometry", "components", "figure_style", "fill", "spacing"}
+               "palette", "accent_on", "page_geometry", "components", "figure_style", "spacing"}
 ACCENT_PLACES = ("title_rule", "callout_rule", "sidebar_rule")
 DIRECTIVE_KEYS = {
     "cover": {"variant", "image", "kicker"},

package/skills/lit-docx/templates/tonalities/brief.yaml

@@ -26,4 +26,3 @@ design:
     allowed: [callout, columns]
     callout_max: 1
   figure_style: {max_height_ratio: 0.40}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.80}

package/skills/lit-docx/templates/tonalities/journal.yaml

@@ -23,4 +23,3 @@ design:
   components:
     allowed: [callout]
   figure_style: {max_height_ratio: 0.40}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.80}

package/skills/lit-docx/templates/tonalities/manual.yaml

@@ -24,4 +24,3 @@ design:
     allowed: [callout, sidebar, columns]
     sidebar: {default_width: third, float: right}
   figure_style: {max_height_ratio: 0.45}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.80}

package/skills/lit-docx/templates/tonalities/memo.yaml

@@ -22,6 +22,5 @@ design:
   components:
     allowed: []
   figure_style: {max_height_ratio: 0.40}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.80}
   # A memo keeps to one page while its content allows: the low end of the line pitch, closer heading space.
   spacing: tight

package/skills/lit-docx/templates/tonalities/proposal.yaml

@@ -24,4 +24,3 @@ design:
     callout_max: 1
     keyfigures: {per_row: 3}
   figure_style: {max_height_ratio: 0.60}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.75}

package/skills/lit-docx/templates/tonalities/report.yaml

@@ -24,4 +24,3 @@ design:
     allowed: [keyfigures, callout, columns]
     keyfigures: {per_row: 3}
   figure_style: {max_height_ratio: 0.45}
-  fill: {min_page_fill: 0.35, target_median_fill: 0.80}

package/skills/lit-pptx/references/tonalities/atlas.md

@@ -34,7 +34,7 @@ colour; the pack's own accent is a quiet navy. Pack file: `templates/tonalities/
 ## Type
 
 Pretendard throughout. Compact ramp at density 10. Titles at normal tracking, display slightly
-tight; figures proportional.
+tight.
 
 ## Dials
 
@@ -73,9 +73,8 @@ Display devices: cover `plate`, statement `drench`, big number on a tint, closin
 
 - Tables `light-grid`: no header fill, row rules, no banding, numbers right-aligned, totals bold.
   A table can only appear inside a family that holds one (kpi-row, a closing).
-- Charts: hairline gridlines, direct labels, annotation off.
-- Images: bleed allowed, crop allowed, no frame; pictures are cropped to their box with their own
-  proportions, never stretched.
+- Charts: hairline gridlines, direct labels.
+- Images: no frame; pictures are cropped to their box with their own proportions, never stretched.
 
 ## Decoration vocabulary
 

package/skills/lit-pptx/references/tonalities/chalk.md

@@ -74,8 +74,8 @@ Display devices: cover `rail`, statement `drench`, big number on a tint, closing
 
 - Tables `header-fill`: a pale apricot header with dark rust labels, row rules, no banding, numbers
   right-aligned, totals bold.
-- Charts (if a chart appears in a table-insight): hairline gridlines, direct labels, annotation on.
-- Images bleed on one side only, no crop, no frame.
+- Charts (if a chart appears in a table-insight): hairline gridlines, direct labels.
+- Images: no frame.
 
 ## Decoration vocabulary
 

package/skills/lit-pptx/references/tonalities/gazette.md

@@ -33,7 +33,7 @@ Pack file: `templates/tonalities/gazette/pack.yaml`.
 
 ## Type
 
-Pretendard throughout. Compact ramp at density 10 (body 13 pt, tables 11 pt). Figures tabular.
+Pretendard throughout. Compact ramp at density 10 (body 13 pt, tables 11 pt).
 
 ## Dials
 
@@ -71,8 +71,8 @@ outline, and `index: true`: a section page repeats the agenda with the current p
 
 - Tables `header-fill`: slate blue header with white labels, a full grid of rules, pale slate
   banding, numbers right-aligned, totals bold. The densest table style of the eight.
-- Charts: hairline gridlines, direct labels, annotation off.
-- Images: no bleed, no crop, hairline frame.
+- Charts: hairline gridlines, direct labels.
+- Images: hairline frame.
 
 ## Decoration vocabulary