cli-jaw 1.6.4 → 1.6.7

package/public/js/render.ts

@@ -288,10 +288,18 @@ export function shieldMath(text: string): { text: string; blocks: MathBlock[] }
     return { text: processed, blocks };
 }
 
-export function unshieldMath(html: string, blocks: MathBlock[]): string {
+export function unshieldMath(html: string, blocks: MathBlock[], isStreaming = false): string {
     return html.replace(/\x00MATH-(\d+)\x00/g, (_, i) => {
         const block = blocks[Number(i)];
         if (!block) return `<code title="math placeholder error">[math error]</code>`;
+
+        // During streaming: lightweight placeholder, defer KaTeX to finalize
+        if (isStreaming) {
+            return block.displayMode
+                ? `<div class="math-placeholder">${escapeHtml(block.tex)}</div>`
+                : `<code class="math-placeholder">${escapeHtml(block.tex)}</code>`;
+        }
+
         try {
             return katex.renderToString(block.tex, {
                 displayMode: block.displayMode,
@@ -397,8 +405,9 @@ async function renderSingleMermaid(el: HTMLElement): Promise<void> {
     }
 }
 
-async function renderMermaidBlocks(): Promise<void> {
-    const pending = document.querySelectorAll('.mermaid-pending');
+async function renderMermaidBlocks(scope?: HTMLElement | Document): Promise<void> {
+    const root = scope || document;
+    const pending = root.querySelectorAll('.mermaid-pending');
     if (!pending.length) return;
     ensureMermaidObserver();
     for (const el of pending) {
@@ -453,8 +462,9 @@ function ensureMarked(): boolean {
 }
 
 // ── Rehighlight all code blocks ──
-export function rehighlightAll(): void {
-    document.querySelectorAll('.code-block pre code, .code-block-wrapper pre code').forEach(el => {
+export function rehighlightAll(scope?: HTMLElement | Document): void {
+    const root = scope || document;
+    root.querySelectorAll('.code-block pre code, .code-block-wrapper pre code').forEach(el => {
         if ((el as HTMLElement).dataset.highlighted === 'yes') return;
         const lang = [...el.classList].find(c => c.startsWith('language-'))?.replace('language-', '');
         const raw = el.textContent || '';
@@ -676,14 +686,14 @@ function unshieldSvgBlocks(html: string, blocks: SvgBlock[]): string {
 
 // ── Diagram Zoom Overlay ──
 
-export function bindDiagramZoom(): void {
-    document.querySelectorAll('.diagram-zoom-btn').forEach(btn => {
+export function bindDiagramZoom(scope?: HTMLElement | Document): void {
+    const root = scope || document;
+    root.querySelectorAll('.diagram-zoom-btn').forEach(btn => {
         if ((btn as HTMLElement).dataset.bound) return;
         (btn as HTMLElement).dataset.bound = '1';
         btn.addEventListener('click', () => {
             const container = btn.closest('.diagram-container');
             if (!container) return;
-            // Clone without zoom button to prevent nesting
             const clone = container.cloneNode(true) as HTMLElement;
             clone.querySelectorAll('.diagram-zoom-btn, .diagram-copy-btn, .diagram-save-btn').forEach(b => b.remove());
             openDiagramOverlay(clone.innerHTML);
@@ -773,7 +783,7 @@ export function renderMarkdown(text: string, isStreaming = false): string {
     html = html.replace(/<table/g, '<div class="table-wrapper"><table').replace(/<\/table>/g, '</table></div>');
 
     // 6. Unshield math
-    html = unshieldMath(html, mathBlocks);
+    html = unshieldMath(html, mathBlocks, isStreaming);
 
     // 7. Sanitize
     html = sanitizeHtml(html);
@@ -781,15 +791,34 @@ export function renderMarkdown(text: string, isStreaming = false): string {
     // 8. Unshield SVGs (after sanitize — SVGs sanitized individually in renderSvgBlock)
     html = unshieldSvgBlocks(html, svgBlocks);
 
-    // 9. Post-render async tasks
-    requestAnimationFrame(() => {
-        renderMermaidBlocks();
-        rehighlightAll();
-        bindDiagramZoom();
-    });
+    // 9. Post-render async tasks — skip during streaming (deferred to finalize)
+    if (!isStreaming) {
+        schedulePostRender();
+    }
 
     ensureCopyDelegation();
     ensureDiagramActionDelegation();
 
     return html;
 }
+
+// ── Batched post-render scheduler ──
+// Coalesces multiple renderMarkdown() calls into a single post-render pass.
+let postRenderRAF: number | null = null;
+
+function schedulePostRender(): void {
+    if (postRenderRAF) return;
+    postRenderRAF = requestAnimationFrame(() => {
+        postRenderRAF = null;
+        renderMermaidBlocks();
+        rehighlightAll();
+        bindDiagramZoom();
+    });
+}
+
+export function cancelPostRender(): void {
+    if (postRenderRAF) {
+        cancelAnimationFrame(postRenderRAF);
+        postRenderRAF = null;
+    }
+}

package/public/js/streaming-render.ts

@@ -1,11 +1,14 @@
 // ── Streaming rAF Renderer ──
-// Phase 3/8: throttled markdown rendering during agent streaming
+// Throttled markdown rendering during agent streaming.
 // Prevents flicker by batching renders to 1 per animation frame.
+// Array buffer avoids O(n) string copy per chunk.
 
 import { renderMarkdown } from './render.js';
 
 export interface StreamState {
+    chunks: string[];
     fullText: string;
+    textDirty: boolean;
     element: HTMLElement;
     pendingRAF: number | null;
     isFinalized: boolean;
@@ -16,26 +19,39 @@ const FULL_RENDER_THRESHOLD = 2000;
 const THROTTLE_MS = 80;  // ~12fps — was 32ms (30fps), reduced to avoid blocking input
 
 export function createStreamRenderer(el: HTMLElement): StreamState {
-    return { fullText: '', element: el, pendingRAF: null, isFinalized: false, lastRenderTime: 0 };
+    return {
+        chunks: [], fullText: '', textDirty: false,
+        element: el, pendingRAF: null, isFinalized: false, lastRenderTime: 0,
+    };
+}
+
+function getFullText(ss: StreamState): string {
+    if (ss.textDirty) {
+        ss.fullText = ss.chunks.join('');
+        ss.textDirty = false;
+    }
+    return ss.fullText;
 }
 
 export function appendChunk(ss: StreamState, chunk: string): void {
-    ss.fullText += chunk;
+    ss.chunks.push(chunk);
+    ss.textDirty = true;
+
     if (!ss.pendingRAF && !ss.isFinalized) {
         ss.pendingRAF = requestAnimationFrame(() => {
             ss.pendingRAF = null;
             if (ss.isFinalized) return;
             const now = performance.now();
-            if (ss.fullText.length < FULL_RENDER_THRESHOLD || now - ss.lastRenderTime > THROTTLE_MS) {
-                ss.element.innerHTML = renderMarkdown(ss.fullText, true) +
+            const text = getFullText(ss);
+            if (text.length < FULL_RENDER_THRESHOLD || now - ss.lastRenderTime > THROTTLE_MS) {
+                ss.element.innerHTML = renderMarkdown(text, true) +
                     '<span class="stream-cursor" aria-hidden="true"></span>';
                 ss.lastRenderTime = now;
             } else {
-                // Throttled — schedule trailing render to ensure latest text paints
                 ss.pendingRAF = requestAnimationFrame(() => {
                     ss.pendingRAF = null;
                     if (ss.isFinalized) return;
-                    ss.element.innerHTML = renderMarkdown(ss.fullText, true) +
+                    ss.element.innerHTML = renderMarkdown(getFullText(ss), true) +
                         '<span class="stream-cursor" aria-hidden="true"></span>';
                     ss.lastRenderTime = performance.now();
                 });
@@ -44,12 +60,19 @@ export function appendChunk(ss: StreamState, chunk: string): void {
     }
 }
 
-export function finalizeStream(ss: StreamState): string {
+/**
+ * Finalize streaming session. Returns accumulated text.
+ * @param skipRender true when caller (finalizeAgent) will do its own full render.
+ */
+export function finalizeStream(ss: StreamState, skipRender = false): string {
     ss.isFinalized = true;
     if (ss.pendingRAF) {
         cancelAnimationFrame(ss.pendingRAF);
         ss.pendingRAF = null;
     }
-    ss.element.innerHTML = renderMarkdown(ss.fullText);
-    return ss.fullText;
+    const text = getFullText(ss);
+    if (!skipRender) {
+        ss.element.innerHTML = renderMarkdown(text);
+    }
+    return text;
 }

package/public/js/ui.ts

@@ -85,8 +85,7 @@ export function updateQueueBadge(count: number): void {
 function showSkeleton(): void {
     const container = document.getElementById('chatMessages');
     if (!container || container.querySelector('.skeleton-msg')) return;
-    const vs = getVirtualScroll();
-    if (vs.active) vs.flushToDOM();
+    // No flushToDOM — skeleton goes directly into container as overlay
     hideEmptyState();
     const skel = document.createElement('div');
     skel.className = 'skeleton-msg';
@@ -236,7 +235,7 @@ export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
         }
         const content = (state.currentAgentDiv as HTMLElement)?.querySelector('.msg-content');
         // Live stream is preview-only; agent_done text stays authoritative.
-        const streamedText = currentStream ? finalizeStream(currentStream) : '';
+        const streamedText = currentStream ? finalizeStream(currentStream, true) : '';
         const finalText = text || streamedText;
         currentStream = null;
         // Skip static tool HTML when process block already shows tool summary
@@ -244,6 +243,13 @@ export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
         if (content) content.innerHTML = toolHtml + renderMarkdown(finalText);
         if (content) content.setAttribute('data-raw', stripOrchestration(finalText));
         if (content) activateWidgets(content as HTMLElement);
+
+        // Promote streaming div from real DOM into VS if active
+        const vs = getVirtualScroll();
+        if (vs.active && state.currentAgentDiv && state.currentAgentDiv.isConnected) {
+            vs.appendLiveItem(state.currentAgentDiv);
+            state.currentAgentDiv.remove();
+        }
     }
     currentStream = null;
     state.currentAgentDiv = null;
@@ -257,7 +263,6 @@ export function finalizeAgent(text: string, toolLog?: ToolLogEntry[]): void {
 export function addMessage(role: string, text: string, cli?: string | null): HTMLDivElement {
     const container = document.getElementById('chatMessages');
     const vs = getVirtualScroll();
-    if (vs.active) vs.flushToDOM();
     hideEmptyState();
     removeSkeleton();
 
@@ -274,8 +279,17 @@ export function addMessage(role: string, text: string, cli?: string | null): HTM
     }
     const contentEl = div.querySelector('.msg-content');
     if (contentEl) contentEl.setAttribute('data-raw', stripOrchestration(text));
-    container?.appendChild(div);
-    activateWidgets(div);
+
+    // Streaming placeholder (agent + empty text) must stay in real DOM
+    // so state.currentAgentDiv reference remains valid during streaming.
+    const isStreamingPlaceholder = role === 'agent' && !text;
+
+    if (vs.active && !isStreamingPlaceholder) {
+        vs.appendLiveItem(div);
+    } else {
+        container?.appendChild(div);
+        activateWidgets(div);
+    }
     scrollToBottom();
     return div;
 }
@@ -337,22 +351,40 @@ export async function loadMessages(): Promise<void> {
         if (chatEl) chatEl.innerHTML = '';
 
         if (msgs.length >= VS_THRESHOLD) {
+            // Phase 2: lazy render — store skeleton HTML, render on viewport entry
             for (const m of msgs) {
                 const role = m.role === 'assistant' ? 'agent' : m.role;
-                const rendered = renderMarkdown(m.content);
+                const rawContent = stripOrchestration(m.content);
                 const label = escapeHtml(role === 'user' ? t('msg.you') : getAppName());
                 const tools = m.role === 'assistant' ? parseToolLog(m.tool_log) : [];
                 const toolHtml = tools.length > 0 ? buildProcessBlockHtml(toProcessSteps(tools), true) : '';
+                // Skeleton placeholder — lazy-pending class triggers render on viewport entry
+                const skeletonContent = '<div class="skeleton-line"></div><div class="skeleton-line"></div>';
                 const html = role === 'agent'
-                    ? `<div class="msg msg-agent"><div class="agent-icon" aria-hidden="true">${getAgentIcon(m.cli)}</div><div class="agent-body">${toolHtml}<div class="msg-content" data-raw="${escapeHtml(stripOrchestration(m.content))}">${rendered}</div><button class="msg-copy" title="Copy" aria-label="Copy message"></button></div></div>`
-                    : `<div class="msg msg-${role}"><div class="msg-label">${label}</div><div class="msg-content" data-raw="${escapeHtml(stripOrchestration(m.content))}">${rendered}</div><button class="msg-copy" title="Copy" aria-label="Copy message"></button></div>`;
+                    ? `<div class="msg msg-agent"><div class="agent-icon" aria-hidden="true">${getAgentIcon(m.cli)}</div><div class="agent-body">${toolHtml}<div class="msg-content lazy-pending" data-raw="${escapeHtml(rawContent)}">${skeletonContent}</div><button class="msg-copy" title="Copy" aria-label="Copy message"></button></div></div>`
+                    : `<div class="msg msg-${role}"><div class="msg-label">${label}</div><div class="msg-content lazy-pending" data-raw="${escapeHtml(rawContent)}">${skeletonContent}</div><button class="msg-copy" title="Copy" aria-label="Copy message"></button></div>`;
                 vs.addItem(crypto.randomUUID(), html);
             }
+
+            // Register lazy render callback
+            vs.onLazyRender = (targets: HTMLElement[]) => {
+                for (const el of targets) {
+                    if (!el.classList.contains('lazy-pending')) continue;
+                    const raw = el.getAttribute('data-raw') || '';
+                    el.innerHTML = raw ? renderMarkdown(raw) : '';
+                    el.classList.remove('lazy-pending');
+                    activateWidgets(el);
+
+                    // Persist rendered HTML back into VS cache
+                    const msgEl = el.closest('[data-vs-idx]') as HTMLElement | null;
+                    if (msgEl) {
+                        const idx = Number(msgEl.dataset.vsIdx);
+                        vs.updateItemHtml(idx, msgEl.outerHTML);
+                    }
+                }
+            };
+
             vs.scrollToBottom();
-            requestAnimationFrame(() => {
-                const chatElRef = document.getElementById('chatMessages');
-                if (chatElRef) activateWidgets(chatElRef);
-            });
         } else {
             msgs.forEach(m => {
                 const div = addMessage(m.role === 'assistant' ? 'agent' : m.role, m.content, m.cli);

package/public/js/virtual-scroll.ts

@@ -2,7 +2,7 @@
 // Activates at THRESHOLD messages to prevent DOM bloat
 // Below threshold: standard DOM append (zero overhead)
 
-const THRESHOLD = 200;
+const THRESHOLD = 80;
 const BUFFER = 5;
 const EST_HEIGHT = 80;
 
@@ -12,6 +12,8 @@ export interface VirtualItem {
     height: number;
 }
 
+export type LazyRenderCallback = (targets: HTMLElement[]) => void;
+
 export class VirtualScroll {
     private items: VirtualItem[] = [];
     private container: HTMLElement;
@@ -19,10 +21,14 @@ export class VirtualScroll {
     private spacerBottom: HTMLDivElement;
     private viewport: HTMLDivElement;
     private _active = false;
+    private _totalHeight = 0;
     private rafId: number | null = null;
     private firstVisible = 0;
     private lastVisible = 0;
 
+    /** Called after render() mounts items in viewport — for lazy rendering */
+    onLazyRender: LazyRenderCallback | null = null;
+
     constructor(containerId: string) {
         this.container = document.getElementById(containerId)!;
         this.spacerTop = document.createElement('div');
@@ -37,22 +43,23 @@ export class VirtualScroll {
     get count(): number { return this.items.length; }
 
     /** Flush all virtual items to real DOM and deactivate VS.
-     *  Called before live message append to prevent spacer/DOM conflicts. */
+     *  Called on conversation clear or explicit reset. */
     flushToDOM(): void {
         if (!this._active) return;
         this.container.removeEventListener('scroll', this.scrollHandler);
         if (this.rafId) { cancelAnimationFrame(this.rafId); this.rafId = null; }
-        // Render all items as real DOM nodes
         this.container.innerHTML = this.items.map(it => it.html).join('');
         this._active = false;
         this.firstVisible = 0;
         this.lastVisible = 0;
-        // Release items to free memory (DOM now owns the content)
         this.items = [];
+        this._totalHeight = 0;
     }
 
     addItem(id: string, html: string): void {
-        this.items.push({ id, html, height: EST_HEIGHT });
+        const item: VirtualItem = { id, html, height: EST_HEIGHT };
+        this.items.push(item);
+        this._totalHeight += EST_HEIGHT;
         if (!this._active && this.items.length >= THRESHOLD) {
             this.activate();
         }
@@ -61,18 +68,38 @@ export class VirtualScroll {
         }
     }
 
+    /** Append a live DOM element while keeping VS active.
+     *  Serializes to HTML for virtual storage. */
+    appendLiveItem(div: HTMLElement): void {
+        if (!this._active) return;
+        const html = div.outerHTML;
+        const id = crypto.randomUUID();
+        const item: VirtualItem = { id, html, height: EST_HEIGHT };
+        this.items.push(item);
+        this._totalHeight += EST_HEIGHT;
+        this.scheduleRender();
+        this.scrollToBottom();
+    }
+
+    /** Update cached HTML for a specific item index (used by lazy render). */
+    updateItemHtml(idx: number, html: string): void {
+        if (this.items[idx]) {
+            this.items[idx].html = html;
+        }
+    }
+
     private scrollHandler = () => this.scheduleRender();
 
     private activate(): void {
         this._active = true;
-        // Measure existing DOM nodes
+        this._totalHeight = 0;
         const existing = this.container.querySelectorAll('.msg');
         existing.forEach((el, i) => {
             if (this.items[i]) {
                 this.items[i].height = el.getBoundingClientRect().height;
+                this._totalHeight += this.items[i].height;
             }
         });
-        // Replace DOM with virtual structure
         this.container.innerHTML = '';
         this.container.append(this.spacerTop, this.viewport, this.spacerBottom);
         this.container.addEventListener('scroll', this.scrollHandler, { passive: true });
@@ -91,7 +118,6 @@ export class VirtualScroll {
         const scrollTop = this.container.scrollTop;
         const viewHeight = this.container.clientHeight;
 
-        // Binary-ish search for start index
         let accum = 0;
         let startIdx = 0;
         for (let i = 0; i < this.items.length; i++) {
@@ -112,12 +138,10 @@ export class VirtualScroll {
         }
         const last = Math.min(this.items.length - 1, endIdx + BUFFER);
 
-        // Skip re-render if range unchanged
         if (first === this.firstVisible && last === this.lastVisible) return;
         this.firstVisible = first;
         this.lastVisible = last;
 
-        // Compute spacer heights
         let topSpace = 0;
         for (let i = 0; i < first; i++) topSpace += this.items[i].height;
         let bottomSpace = 0;
@@ -126,7 +150,6 @@ export class VirtualScroll {
         this.spacerTop.style.height = `${topSpace}px`;
         this.spacerBottom.style.height = `${bottomSpace}px`;
 
-        // Render visible items
         const frag = document.createDocumentFragment();
         for (let i = first; i <= last; i++) {
             const item = this.items[i];
@@ -141,26 +164,36 @@ export class VirtualScroll {
         this.viewport.innerHTML = '';
         this.viewport.appendChild(frag);
 
-        // Re-measure rendered heights
+        // Re-measure rendered heights and update totalHeight
         this.viewport.querySelectorAll('[data-vs-idx]').forEach(el => {
             const idx = Number((el as HTMLElement).dataset.vsIdx);
             if (this.items[idx]) {
-                this.items[idx].height = el.getBoundingClientRect().height;
+                const oldH = this.items[idx].height;
+                const newH = el.getBoundingClientRect().height;
+                this.items[idx].height = newH;
+                this._totalHeight += (newH - oldH);
             }
         });
+
+        // Fire lazy render callback for newly visible items
+        if (this.onLazyRender) {
+            const lazyTargets = this.viewport.querySelectorAll<HTMLElement>('.lazy-pending');
+            if (lazyTargets.length > 0) {
+                this.onLazyRender(Array.from(lazyTargets));
+            }
+        }
     }
 
     scrollToBottom(): void {
-        const total = this.items.reduce((sum, it) => sum + it.height, 0);
-        this.container.scrollTop = total;
+        this.container.scrollTop = this._totalHeight;
         this.scheduleRender();
     }
 
     clear(): void {
         this.items = [];
+        this._totalHeight = 0;
         if (this._active) {
             this.container.removeEventListener('scroll', this.scrollHandler);
-            // Restore normal DOM structure
             this.viewport.innerHTML = '';
             this.spacerTop.style.height = '0';
             this.spacerBottom.style.height = '0';
@@ -169,6 +202,7 @@ export class VirtualScroll {
         this._active = false;
         this.firstVisible = 0;
         this.lastVisible = 0;
+        this.onLazyRender = null;
         if (this.rafId) {
             cancelAnimationFrame(this.rafId);
             this.rafId = null;

package/public/js/ws.ts

@@ -4,7 +4,7 @@ import { setStatus, updateQueueBadge, addSystemMsg, appendAgentText, finalizeAge
 import { t, getLang } from './features/i18n.js';
 import { getVirtualScroll } from './virtual-scroll.js';
 import { ICONS, emojiToIcon } from './icons.js';
-import { escapeHtml } from './render.js';
+import { escapeHtml, cancelPostRender } from './render.js';
 import type { OrcStateName } from './state.js';
 
 const ROADMAP_PHASES = ['P', 'A', 'B', 'C'] as const;
@@ -258,6 +258,7 @@ export function connect(): void {
         } else if (msg.type === 'orchestrate_done') {
             finalizeAgent(msg.text || '');
         } else if (msg.type === 'clear') {
+            cancelPostRender();
             cleanupToolActivity();
             getVirtualScroll().clear();
             const el = document.getElementById('chatMessages');

package/scripts/ensure-native-modules.cjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * ensure-native-modules.cjs
+ *
+ * Verifies that native addons needed for local runtime are loadable.
+ * If better-sqlite3 exists but was built against a different Node ABI,
+ * rebuild it in-place before build/test steps continue.
+ */
+const { execFileSync } = require('child_process');
+
+const npmBin = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+function loadBetterSqlite3() {
+    try {
+        require('better-sqlite3');
+        return null;
+    } catch (error) {
+        return error;
+    }
+}
+
+function isRecoverableNativeMismatch(error) {
+    const text = String(error && (error.stack || error.message || error));
+    return (
+        text.includes('better_sqlite3.node') ||
+        text.includes('better-sqlite3') ||
+        text.includes('NODE_MODULE_VERSION') ||
+        text.includes('ERR_DLOPEN_FAILED')
+    );
+}
+
+const firstError = loadBetterSqlite3();
+if (!firstError) process.exit(0);
+
+if (!isRecoverableNativeMismatch(firstError)) {
+    console.error('[jaw:native] better-sqlite3 load failed with a non-recoverable error.');
+    console.error(firstError);
+    process.exit(1);
+}
+
+console.warn('[jaw:native] better-sqlite3 load failed — rebuilding native module for current Node runtime...');
+execFileSync(npmBin, ['rebuild', 'better-sqlite3'], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+});
+
+const secondError = loadBetterSqlite3();
+if (secondError) {
+    console.error('[jaw:native] better-sqlite3 is still not loadable after rebuild.');
+    console.error(secondError);
+    process.exit(1);
+}
+
+console.log('[jaw:native] better-sqlite3 is ready for this Node runtime.');

package/scripts/install-officecli.ps1

@@ -0,0 +1,96 @@
+param(
+  [switch]$Force,
+  [switch]$Update,
+  [switch]$Upstream,
+  [string]$Repo = $env:OFFICECLI_REPO
+)
+
+$ErrorActionPreference = "Stop"
+
+function Write-Info($msg) { Write-Host "▸ $msg" -ForegroundColor Cyan }
+function Write-Ok($msg) { Write-Host "✔ $msg" -ForegroundColor Green }
+function Write-Warn($msg) { Write-Host "⚠ $msg" -ForegroundColor Yellow }
+function Fail($msg) { Write-Host "✖ $msg" -ForegroundColor Red; exit 1 }
+
+if ($Upstream -and $env:OFFICECLI_REPO) {
+  Fail "--upstream cannot be combined with OFFICECLI_REPO"
+}
+
+if (-not $Repo) {
+  $Repo = "lidge-jun/OfficeCLI"
+}
+if ($Upstream) {
+  $Repo = "iOfficeAI/OfficeCLI"
+}
+
+$installDir = Join-Path $env:LOCALAPPDATA "OfficeCli"
+$targetBin = Join-Path $installDir "officecli.exe"
+$downloadBin = Join-Path $installDir "officecli.download.exe"
+
+$arch = [System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture.ToString().ToLowerInvariant()
+switch ($arch) {
+  "x64" { $asset = "officecli-win-x64.exe" }
+  "arm64" { $asset = "officecli-win-arm64.exe" }
+  default { Fail "Unsupported Windows architecture: $arch" }
+}
+
+function Normalize-Version([string]$version) {
+  if (-not $version) { return "" }
+  return $version.Trim().TrimStart('v')
+}
+
+function Get-LatestTag([string]$repoName) {
+  $release = Invoke-RestMethod -Uri "https://api.github.com/repos/$repoName/releases/latest" -Headers @{ "User-Agent" = "cli-jaw-postinstall" }
+  return [string]$release.tag_name
+}
+
+Write-Info "Platform: win32/$arch -> $asset"
+
+if ((Test-Path $targetBin) -and -not $Force -and -not $Update) {
+  try {
+    $current = & $targetBin --version 2>$null
+    Write-Ok "officecli already installed: v$($current.Trim())"
+    Write-Host "  Use -Force to reinstall or -Update to refresh only when outdated"
+    exit 0
+  } catch {
+    Write-Warn "Existing officecli is not executable; reinstalling"
+  }
+}
+
+if ((Test-Path $targetBin) -and -not $Force -and $Update) {
+  $current = ""
+  $latest = ""
+  try { $current = & $targetBin --version 2>$null } catch { }
+  try { $latest = Get-LatestTag $Repo } catch { }
+  if ($current -and $latest -and (Normalize-Version $current) -eq (Normalize-Version $latest)) {
+    Write-Ok "officecli already up to date: v$(Normalize-Version $current)"
+    exit 0
+  }
+  if ($current -and $latest) {
+    Write-Info "Updating officecli v$(Normalize-Version $current) -> v$(Normalize-Version $latest)"
+  } else {
+    Write-Warn "Could not compare installed version with latest release; reinstalling"
+  }
+}
+
+New-Item -ItemType Directory -Force -Path $installDir | Out-Null
+$downloadUrl = "https://github.com/$Repo/releases/latest/download/$asset"
+
+Write-Info "Downloading officecli from $Repo..."
+Invoke-WebRequest -Uri $downloadUrl -OutFile $downloadBin
+
+try {
+  $version = (& $downloadBin --version 2>$null).Trim()
+} catch {
+  Remove-Item -Force $downloadBin -ErrorAction SilentlyContinue
+  Fail "Binary exists but won't execute"
+}
+
+Move-Item -Force $downloadBin $targetBin
+Write-Ok "officecli v$version installed -> $targetBin"
+
+$pathEntries = (($env:PATH -split ';') | ForEach-Object { $_.Trim() }) | Where-Object { $_ }
+if (-not ($pathEntries -contains $installDir)) {
+  Write-Warn "officecli is not on PATH. Add this location if you want to run it directly:"
+  Write-Host "  $installDir"
+}