@wonseok-han/confluence-sync 1.8.0 → 2.0.0

package/dist/web/table-format.js

@@ -0,0 +1,224 @@
+import { readFile, realpath, stat, mkdtemp, writeFile, rename, rm } from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { createDocument } from '@mixmark-io/domino';
+import { htmlTableMarkdown } from '../documents/html-tables.js';
+import { splitFrontmatter } from '../documents/obsidian.js';
+import { applyTableWidths, tableWidths } from '../documents/tables.js';
+import { formatDocument } from '../documents/format.js';
+import { readPreviewSource } from './document-source.js';
+export const sourceHash = (source) => createHash('sha256').update(source).digest('hex');
+/** Source ranges come from Markdown tokens, never from the preview's sanitized HTML. */
+function targets(source) {
+    const { body } = splitFrontmatter(source);
+    const prefix = source.length - body.length;
+    const lines = body.split('\n');
+    const offsets = [prefix];
+    for (const line of lines)
+        offsets.push(offsets.at(-1) + line.length + 1);
+    const md = htmlTableMarkdown();
+    const tokens = md.parse(body, {});
+    const result = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type === 'table_open' && token.map) {
+            let end = i;
+            while (tokens[end]?.type !== 'table_close')
+                end++;
+            result.push(token.level === 0 ? { start: offsets[token.map[0]], end: Math.min(source.length, offsets[token.map[1]]), html: md.renderer.render(tokens.slice(i, end + 1), md.options, {}), markdown: true } : null);
+            i = end;
+        }
+        else if (token.type === 'html_block' && token.map) {
+            const count = createDocument(token.content).querySelectorAll('table').length;
+            const start = offsets[token.map[0]];
+            const raw = source.slice(start, Math.min(source.length, offsets[token.map[1]]));
+            const opening = raw.match(/^\s*<table\b(?:[^"'<>]|"[^"]*"|'[^']*')*>/i);
+            const close = raw.match(/<\/table\s*>/i);
+            const target = count === 1 && token.level === 0 && opening && close
+                ? { start: start + raw.indexOf('<'), end: start + close.index + close[0].length, html: raw.slice(raw.indexOf('<'), close.index + close[0].length), markdown: false } : null;
+            for (let n = 0; n < count; n++)
+                result.push(target);
+        }
+    }
+    return result;
+}
+function columnCount(table, visit) {
+    const occupied = [];
+    let count = 0;
+    const rows = Array.from(table.querySelectorAll('tr'));
+    rows.forEach((row, r) => {
+        let column = 0;
+        for (const cell of Array.from(row.children).filter(c => /^(TD|TH)$/.test(c.tagName))) {
+            while ((occupied[column] ?? 0) > r)
+                column++;
+            const span = Math.max(1, Number(cell.getAttribute('colspan')) || 1);
+            const rawRows = cell.getAttribute('rowspan');
+            const rowSpan = rawRows === '0' ? rows.length - r : Math.max(1, Number(rawRows) || 1);
+            if (!Number.isInteger(span) || span > 32 || !Number.isInteger(rowSpan))
+                return;
+            visit?.(cell, column, span);
+            for (let n = 0; n < span; n++)
+                occupied[column + n] = r + rowSpan;
+            column += span;
+        }
+        count = Math.max(count, column, occupied.length);
+    });
+    return count;
+}
+/** Visual-length estimate: wide characters count twice; row/column spans use logical columns. */
+function contentWeights(table, count) {
+    const samples = Array.from({ length: count }, () => []);
+    columnCount(table, (cell, column, span) => {
+        const text = (cell.textContent ?? '').normalize('NFC').replace(/\s+/g, ' ').trim();
+        let length = 0;
+        for (const character of text) {
+            if (/\p{Mark}|[\u200d\ufe0e\ufe0f]/u.test(character))
+                continue;
+            length += /\p{Script=Hangul}|\p{Script=Han}|\p{Script=Hiragana}|\p{Script=Katakana}|\p{Extended_Pictographic}/u.test(character) ? 2 : 1;
+        }
+        for (let i = column; i < Math.min(count, column + span); i++)
+            samples[i].push(length / span);
+    });
+    return samples.map(values => {
+        values.sort((a, b) => a - b);
+        const typical = values[Math.ceil((values.length - 1) * 0.75)] ?? 0;
+        const longest = values.at(-1) ?? 0;
+        // Compress long prose, and limit a single unusually long cell's influence.
+        return Math.max(1, Math.sqrt(typical) * 0.8 + Math.sqrt(Math.min(longest, typical * 2)) * 0.2);
+    });
+}
+export function editableTables(source) {
+    return targets(source).map((target, index) => {
+        const table = target && createDocument(target.html).querySelector('table');
+        const count = table ? columnCount(table) : 0;
+        if (!table || count < 1 || count > 32)
+            return { index, widths: [], editable: false };
+        const dimensions = tableWidths(table);
+        const total = Math.round(Math.max(count * 40, Math.min(3000, dimensions.width ?? 760)));
+        const existing = dimensions.columns.length === count && dimensions.columns.every(w => w !== undefined) ? dimensions.columns : Array(count).fill(1);
+        const sum = existing.reduce((a, b) => a + b, 0);
+        const widths = existing.map(w => Math.max(40, Math.floor(w / sum * total)));
+        let remaining = total - widths.reduce((a, b) => a + b, 0);
+        while (remaining !== 0) {
+            const column = remaining > 0 ? widths.indexOf(Math.min(...widths)) : widths.indexOf(Math.max(...widths));
+            widths[column] += remaining > 0 ? 1 : -1;
+            remaining += remaining > 0 ? -1 : 1;
+        }
+        return { index, widths, editable: true, contentWeights: contentWeights(table, count) };
+    });
+}
+export function formatTable(source, index, widths) {
+    const list = targets(source);
+    const target = list[index];
+    const info = editableTables(source)[index];
+    if (!target || !info?.editable || !Number.isInteger(index))
+        throw new Error('이 표는 너비 편집을 지원하지 않습니다.');
+    if (!Array.isArray(widths) || widths.length !== info.widths.length || widths.some(w => !Number.isInteger(w) || w < 40 || w > 3000)
+        || widths.reduce((a, b) => a + b, 0) > 3000)
+        throw new Error('열 너비는 40px 이상, 전체 너비는 3000px 이하여야 합니다.');
+    const table = createDocument(target.html).querySelector('table');
+    const signature = (el) => Array.from(el.querySelectorAll('th, td')).map(c => [c.innerHTML, c.getAttribute('colspan'), c.getAttribute('rowspan')]);
+    const before = signature(table);
+    const total = widths.reduce((a, b) => a + b, 0);
+    applyTableWidths(table, { width: total, columns: widths });
+    if (table.hasAttribute('data-table-width'))
+        table.setAttribute('data-table-width', String(total));
+    let html;
+    if (target.markdown)
+        html = table.outerHTML + '\n';
+    else {
+        const opening = table.cloneNode(false);
+        const startTag = opening.outerHTML.slice(0, -'</table>'.length);
+        const group = table.querySelector('colgroup').outerHTML;
+        const original = target.html.replace(/^<table\b(?:[^"'<>]|"[^"]*"|'[^']*')*>/i, startTag);
+        html = /<colgroup\b/i.test(original)
+            ? original.replace(/<colgroup\b[^>]*>[\s\S]*?<\/colgroup\s*>/i, group)
+            : original.replace(startTag, startTag + '\n' + group);
+    }
+    const checked = createDocument(html).querySelector('table');
+    if (JSON.stringify(signature(checked)) !== JSON.stringify(before)
+        || tableWidths(checked).width !== total
+        || JSON.stringify(tableWidths(checked).columns) !== JSON.stringify(widths))
+        throw new Error('표 내용을 보존할 수 없어 변경하지 않았습니다.');
+    return source.slice(0, target.start) + html + source.slice(target.end);
+}
+export function formatAllTables(source, mode) {
+    let after = source;
+    for (const table of editableTables(source).filter(t => t.editable)) {
+        const total = table.widths.reduce((a, b) => a + b, 0), count = table.widths.length;
+        const weights = mode === 'fit' ? table.contentWeights : Array(count).fill(1);
+        const extra = total - count * 40, sum = weights.reduce((a, b) => a + b, 0);
+        const shares = weights.map(w => w / sum * extra), widths = shares.map(w => 40 + Math.floor(w));
+        const order = shares.map((w, i) => ({ i, fraction: w - Math.floor(w) })).sort((a, b) => b.fraction - a.fraction);
+        const rest = total - widths.reduce((a, b) => a + b, 0);
+        for (let i = 0; i < rest; i++)
+            widths[order[i].i]++;
+        after = formatTable(after, table.index, widths);
+    }
+    return after;
+}
+export function createTableFormatting() {
+    const plans = new Map();
+    const plan = (base, file, before, after) => {
+        if (Buffer.byteLength(after) > 1_000_000)
+            throw new Error('변경 결과가 미리보기 지원 크기인 1MB를 넘습니다.');
+        const planId = randomUUID();
+        if (plans.size >= 20)
+            plans.delete(plans.keys().next().value);
+        plans.set(planId, { base, file, before, after });
+        return { planId, before, after };
+    };
+    return {
+        async documentPreview(base, file, hash, basic, tables, changes = []) {
+            if (typeof basic !== 'boolean' || !['keep', 'fit', 'equal'].includes(tables))
+                throw new Error('문서 서식 옵션을 확인해 주세요.');
+            const { source, path } = await readPreviewSource(base, file);
+            if (sourceHash(source) !== hash)
+                throw new Error('파일이 변경되었습니다. 문서 미리보기를 새로고침해 주세요.');
+            if (!Array.isArray(changes) || changes.length > 100 || new Set(changes.map(e => e?.index)).size !== changes.length)
+                throw new Error('표 변경 목록을 확인해 주세요.');
+            let after = source;
+            for (const edit of changes)
+                after = formatTable(after, edit?.index, edit?.widths);
+            if (basic)
+                after = formatDocument(after);
+            if (tables !== 'keep')
+                after = formatAllTables(after, tables);
+            return plan(base, path, source, after);
+        },
+        async preview(base, file, hash, index, widths, changes) {
+            const { source, path } = await readPreviewSource(base, file);
+            if (sourceHash(source) !== hash)
+                throw new Error('파일이 변경되었습니다. 문서 미리보기를 새로고침해 주세요.');
+            const edits = changes ?? [{ index, widths }];
+            if (!Array.isArray(edits) || !edits.length || edits.length > 100 || new Set(edits.map(e => e?.index)).size !== edits.length)
+                throw new Error('표 변경 목록을 확인해 주세요.');
+            let after = source;
+            for (const edit of edits)
+                after = formatTable(after, edit?.index, edit?.widths);
+            return plan(base, path, source, after);
+        },
+        async save(planId) {
+            const plan = plans.get(planId);
+            if (!plan)
+                throw new Error('변경 비교를 다시 실행해 주세요.');
+            const { source, path } = await readPreviewSource(plan.base, plan.file);
+            if (source !== plan.before || path !== plan.file)
+                throw new Error('파일이 변경되어 저장하지 않았습니다. 새로고침 후 다시 비교해 주세요.');
+            const mode = (await stat(path)).mode & 0o777;
+            const stage = await mkdtemp(join(dirname(path), '.csync-table-'));
+            try {
+                const candidate = join(stage, 'document.md');
+                await writeFile(candidate, plan.after, { mode });
+                if (await realpath(plan.file) !== path || await readFile(path, 'utf8') !== plan.before)
+                    throw new Error('파일이 변경되어 저장하지 않았습니다.');
+                await rename(candidate, path);
+                plans.delete(planId);
+            }
+            finally {
+                await rm(stage, { recursive: true, force: true });
+            }
+            return { saved: path };
+        },
+    };
+}

package/dist/web/views/help.js

@@ -1,30 +1,35 @@
+import { tokenGuide } from './token-guide.js';
+import { usageGuide } from './usage-guide.js';
 /** In-app guide for the local document workflow. */
 export const helpDialog = `
 <dialog id="help-dialog" class="help-dialog" aria-labelledby="help-title">
   <header class="help-heading"><div><span class="eyebrow">WORKSPACE GUIDE</span><h2 id="help-title">사용 도움말</h2></div><form method="dialog"><button aria-label="도움말 닫기" autofocus>닫기</button></form></header>
-  <nav class="help-nav" aria-label="도움말 목차"><a href="#help-convert">문서 변환</a><a href="#help-sync">동기화</a><a href="#help-links">참조 링크</a><a href="#help-faq">자주 묻는 질문</a></nav>
+  <nav class="help-nav" aria-label="도움말 목차"><a href="#help-screens">화면으로 보기</a><a href="#help-convert">문서 변환</a><a href="#help-sync">Confluence</a><a href="#help-token">API 토큰 발급</a><a href="#help-links">참조 링크</a><a href="#help-faq">자주 묻는 질문</a></nav>
   <div class="help-body" tabindex="0" aria-label="사용 도움말 내용">
-    <p class="help-intro">Obsidian에서 작업한 문서를 변환한 다음, 변환 결과 폴더를 기준으로 Confluence에 올릴 수 있습니다. 두 탭의 기준 폴더는 각각 설정합니다.</p>
+    <p class="help-intro">Obsidian에서 작업한 문서를 변환한 다음, 변환 결과 폴더를 기준으로 Confluence에 올릴 수 있습니다. 로컬 실행에서는 두 탭의 기준 폴더를 각각 설정합니다. 배포 웹은 로컬 CLI 없이 브라우저에서 문서 폴더를 선택합니다. Vercel 배포에서는 변환·변경 확인을 브라우저에서 처리하고 Confluence 요청만 중계합니다. Docker 배포에서는 문서·첨부·.env를 서버의 임시 공간으로 전달해 처리합니다. 두 방식 모두 로컬 편집 충돌을 확인한 뒤 브라우저가 결과를 저장합니다. 데스크톱 Chrome·Edge와 HTTPS가 필요합니다. 변환 저장 전에 출력 폴더를 선택하세요. 원본과 같은 폴더를 지정하면 저장 시 덮어쓰기 확인창이 뜹니다.</p>
+    ${usageGuide}
     <section id="help-convert"><h3>문서 변환</h3>
-      <ol><li><strong>변환 폴더 선택…</strong>으로 원본 폴더를 엽니다. 화살표는 폴더를 펼치고, 이름을 누르면 변환 대상을 선택합니다.</li><li>파일 하나를 선택하면 그 파일만, 폴더를 선택하면 하위 Markdown 전체를 변환합니다.</li><li>변환 형식과 출력 폴더를 정하고 <strong>미리보기</strong>로 원본과 결과를 비교합니다.</li><li><strong>변환 후 저장</strong>을 누른 뒤 <strong>결과 폴더 열기</strong>로 확인합니다. 웹 변환은 별도 출력 폴더에 저장합니다.</li></ol>
-      <dl><dt>Markdown</dt><dd>찾을 수 있는 위키링크를 상대 링크로 바꾸고 PDF 페이지 참조를 이미지로 변환합니다. 찾지 못한 문서 위키링크는 그대로 남습니다.</dd><dt>Obsidian</dt><dd>해석 가능한 Markdown 문서 링크를 위키링크로 바꿉니다.</dd><dt>Confluence 변환 오류 보정</dt><dd>옛 변환 결과의 CSS 잔해, 불필요한 이스케이프와 코드블록 언어 등을 보정합니다. 미리보기로 바뀐 내용을 확인하세요.</dd><dt>출력 위치</dt><dd>파일 하나는 출력 폴더 바로 아래에, 폴더 전체는 선택 폴더 내부 구조를 유지해 저장합니다. 출력 경로를 비우면 원본 기준 폴더 옆에 새 결과 폴더를 만듭니다.</dd></dl>
+      <ol><li><strong>기준 폴더 변경…</strong>으로 원본 폴더를 엽니다. 화살표는 폴더를 펼치고, 이름을 누르면 변환 대상을 선택합니다.</li><li>파일을 선택하고 기본적으로 접힌 <strong>문서 미리보기</strong>를 펼치면 표와 이미지를 포함한 본문이 표시됩니다. 파일 하나를 선택하면 그 파일만, 폴더를 선택하면 하위 Markdown 전체를 변환합니다. 변환 설정의 기준 폴더 전체 선택을 누르면 현재 탐색 위치와 관계없이 기준 폴더 아래 모든 Markdown을 대상으로 합니다. 선택 후 변환 미리보기와 변환 후 저장을 사용하세요.</li><li>변환 형식과 출력 폴더를 정하고 <strong>변환 미리보기</strong>로 원본과 결과를 비교합니다.</li><li><strong>변환 후 저장</strong>을 누른 뒤 <strong>결과 폴더 열기</strong>로 확인합니다. 웹 변환은 지정한 출력 폴더에 저장하며, 첨부와 PDF 페이지 이미지는 각 문서 옆의 attachments/문서명/에 모읍니다.</li></ol>
+      <dl><dt>Markdown</dt><dd>찾을 수 있는 위키링크를 상대 링크로 바꾸고 PDF 페이지 참조를 이미지로 변환합니다. 찾지 못한 문서 위키링크는 그대로 남습니다.</dd><dt>Obsidian</dt><dd>해석 가능한 Markdown 문서 링크를 위키링크로 바꿉니다.</dd><dt>Confluence 변환 오류 보정</dt><dd>옛 변환 결과의 CSS 잔해, 불필요한 이스케이프와 코드블록 언어 등을 보정합니다. 미리보기로 바뀐 내용을 확인하세요.</dd><dt>출력 위치</dt><dd>파일 하나는 출력 폴더 바로 아래에, 폴더 전체는 선택 폴더 내부 구조를 유지해 저장합니다. 출력 폴더를 원본과 같게 지정하면 선택 범위의 원래 위치에 반영합니다. 실제 덮어쓰기 전 변경 파일을 확인하며, 확인 이후 원본이 바뀌면 저장을 중단합니다. 로컬 실행에서 출력 경로를 비우면 원본 기준 폴더 옆에 새 결과 폴더를 만듭니다.</dd></dl>
     </section>
-    <section id="help-sync"><h3>Confluence 동기화</h3>
-      <ol><li><strong>동기화 폴더 선택…</strong>으로 업로드할 문서가 모인 폴더를 엽니다.</li><li>범위를 고르고 <strong>설정 확인</strong>으로 서버·스페이스·상위 페이지를 확인합니다.</li><li><strong>동기화 미리보기</strong>에서 신규·변경 문서와 링크 경고를 확인합니다. 이 단계는 로컬 비교이며 Confluence에 접속하지 않습니다.</li><li><strong>Confluence에 동기화</strong>를 누르면 실제 업로드합니다. 문서나 설정을 바꾸면 다시 미리보기해야 합니다.</li></ol>
-      <dl><dt>선택 문서</dt><dd>왼쪽에서 선택한 Markdown 문서입니다.</dd><dt>현재 폴더</dt><dd>현재 탐색 중인 폴더와 그 하위 문서입니다. 상위 페이지를 연결하기 위한 처리가 함께 수행될 수 있습니다.</dd><dt>기준 폴더 전체</dt><dd>설정한 동기화 루트의 모든 하위 Markdown입니다. 제외 규칙에 해당하는 문서는 빠집니다.</dd><dt>설정 파일</dt><dd>비우면 기준 폴더의 <code>.env</code>를 사용하고, 없으면 웹 서버 실행 환경을 사용합니다. 다른 설정 파일을 직접 지정할 수도 있습니다.</dd></dl>
-      <p class="help-note">미리보기는 서버의 권한이나 페이지 존재를 검증하지 않습니다. 실행 중 일부 문서가 실패하면 로그를 확인하고 다시 미리보기하세요.</p>
+    <section id="help-sync"><h3>Confluence: Push / Pull</h3>
+      <p>로컬 문서에서 스페이스 문서를 보관할 기준 폴더를 선택하고, .env 연결 설정에서 설정 확인 후 스페이스 연결을 누르세요. 별도 파일·폴더 스코프 설정은 없습니다.</p>
+      <dl><dt>변경사항과 Fetch</dt><dd>로컬은 5초 간격으로 자동 확인하며 Confluence API를 호출하지 않습니다. Fetch는 스페이스 페이지를 100개씩 조회해 새 문서와 버전·위치 변경을 확인하고 2분 동안 결과를 재사용합니다. Push·Pull 성공 후에는 캐시를 건너뛰고 한 번 더 Fetch해 목록을 갱신합니다. 후속 Fetch만 실패하면 완료된 Push·Pull은 유지하고 경고를 표시합니다. 문서와 동기화 기준은 유지합니다.</dd><dt>업로드(Push)</dt><dd>업로드할 문서를 체크하고 미리보기를 완료한 뒤 업로드하세요. 체크한 문서만 처리하며 원격 충돌 검사는 유지합니다. 선택 후 문서를 수정하면 최신 내용 반영과 미리보기가 다시 필요합니다.</dd><dt>가져오기(Pull)</dt><dd>변경 목록 위의 ‘원격 문서 n개 가져오기’로 원격 신규 문서와 원격에서만 바뀐 문서를 받습니다. 로컬이 비어 있어도 같은 기능을 사용합니다. 로컬 수정·의도적인 삭제·양쪽 변경은 보존하며 업로드 체크는 적용되지 않습니다. 문서 버전이 그대로인 첨부 단독 변경은 Fetch에서 감지하지 않습니다. 가져오기 형식은 Markdown 또는 Obsidian을 선택하며, 가져오기와 복구·원복에 적용합니다. 내부 링크 표기와 패널 복원 방식이 달라집니다. Markdown은 제목이 있는 인용문과 위첨자 각주 목록으로, Obsidian은 콜아웃과 정의형·인라인 각주로 복원합니다. 정확한 각주 복원 정보는 새 업로드부터 보관합니다. 기존 파일을 일괄 변환하지 않습니다.</dd><dt>문서 복구·원복</dt><dd>각 문서 행에서 원격에서 복구 또는 원격으로 원복을 누르고 확인하세요. 원복은 해당 문서와 참조 첨부의 로컬 수정을 버립니다. 원격 문서는 변경하지 않으며 복구한 문서는 업로드 선택에서 제외됩니다.</dd><dt>왼쪽 문서 탐색</dt><dd>파일을 선택하면 문서를 미리볼 수 있습니다. 탐색 위치를 바꿔도 작업공간이나 업로드 선택은 바뀌지 않습니다. 제외 규칙과 독립된 하위 작업공간은 유지합니다.</dd><dt>다운로드</dt><dd>.env 연결 설정에서 빈 .env 샘플을 내려받아 값을 채우세요. 대상 및 실행 내역의 로그 다운로드는 현재 작업의 진행·성공·실패 로그를 저장합니다. 토큰은 가려지지만 문서 경로와 오류 메시지는 포함됩니다.</dd><dt>설정 파일</dt><dd>기준 폴더의 .env 또는 직접 가져온 .env를 사용합니다. 가져온 값은 현재 웹 작업에만 적용되며 별도 저장 버튼으로 기준 폴더에 저장할 수 있습니다. 서버 실행 환경을 대신 사용하지 않습니다.</dd></dl>
+      <p class="help-note">Pull은 원격 삭제를 로컬에 자동 반영하거나 양쪽 변경을 자동 병합하지 않습니다. 누락된 원격 첨부는 원격 참조를 유지하고 경고하며, 권한·네트워크 오류는 중단합니다. 기존 원격 루트 연결과 문서 매핑은 임의로 변경하지 않습니다.</p>
     </section>
+    ${tokenGuide}
     <section id="help-links"><h3>다른 폴더의 문서와 연결하기</h3>
       <p>업로드할 문서는 프로젝트 폴더에 있고, 연결할 문서는 별도 DBP 폴더에 있다면 <strong>참조 문서 폴더</strong>에 DBP의 동기화 루트를 추가하세요. 여러 경로를 한 줄씩 입력하거나 폴더 선택창으로 추가할 수 있습니다.</p>
       <pre><code>[[원본/긴/경로/문서명|표시 이름]]
 [표시 이름](../이전/문서명.md)</code></pre>
       <p>먼저 경로로 찾고, 찾지 못하면 기준·참조 폴더에서 파일명으로 찾습니다. 후보가 하나일 때만 연결하며 <code>|</code> 오른쪽은 화면에 표시할 이름입니다.</p>
-      <ul><li>현재 루트의 문서는 그 문서의 페이지 제목으로 연결합니다. 파일명과 H1이 달라도 됩니다.</li><li>참조 문서는 <code>.confluence-sync.json</code>의 게시된 페이지 ID로 연결합니다. 참조 문서 자체는 업로드하지 않습니다.</li><li>같은 Confluence 서버의 별도 동기화 폴더를 지정하세요. 중복 파일명, 문서 누락, 게시 매핑 누락은 경고로 표시합니다.</li></ul>
+      <ul><li>현재 루트의 문서는 그 문서의 페이지 제목으로 연결합니다. 파일명과 H1이 달라도 됩니다.</li><li>참조 문서는 <code>.csync/mapping.json</code>의 게시된 페이지 ID로 연결합니다. 참조 문서 자체는 업로드하지 않습니다.</li><li>같은 Confluence 서버의 별도 동기화 폴더를 지정하세요. 중복 파일명, 문서 누락, 게시 매핑 누락은 경고로 표시합니다.</li></ul>
       <p class="help-note">링크 경고가 있어도 업로드할 수 있습니다. 해결하지 못한 링크는 원문으로 남으므로 실행 전에 경고를 확인하세요.</p>
     </section>
     <section id="help-faq"><h3>자주 묻는 질문</h3>
+      <details><summary>문서와 표 서식을 한 번에 정리할 수 있나요?</summary><p>문서를 선택하고 문서 미리보기의 문서 서식 정리를 열고 기본 서식 정리 버튼을 누르면 정리 결과를 바로 비교합니다. 저장을 눌러야 파일에 반영됩니다. 기존 너비 유지가 기본입니다. 문서 서식 정리 안의 모든 표 메뉴에서 내용에 맞춤·균등 배분을 선택할 수 있습니다. 표 하나를 조절하려면 같은 툴바의 표 직접 편집을 누른 뒤 표를 클릭하세요. 미저장 표 조절도 기본 서식 정리 결과와 함께 확인할 수 있습니다. 오른쪽 변경 비교는 표 조절만 비교합니다. 내용에 맞춤으로 글자 길이에 따라 자동 배분하거나, 열 경계 드래그·균등 배분·전체 너비를 조절한 뒤, 변경 비교에서 원본 파일에 저장합니다. 일반 Markdown 표는 HTML로 변환됩니다. 파일을 바꾸거나 새로고침하면 미저장 변경은 취소됩니다.</p></details>
       <details><summary>기존 파일이 있는데 덮어쓰기 확인창이 안 나와요.</summary><p>내용이 같으면 파일을 건드리지 않고 재사용합니다. 내용이 다른 경우에만 대상 목록을 보여주고 덮어쓸지 확인합니다. 취소하면 저장하지 않습니다.</p></details>
-      <details><summary>문서를 검색했는데 나오지 않아요.</summary><p>검색은 선택한 기준 폴더의 모든 하위 Markdown 파일명을 대상으로 합니다. 본문은 검색하지 않으며 숨김 폴더와 node_modules는 제외됩니다.</p></details>
+      <details><summary>문서를 검색했는데 나오지 않아요.</summary><p>검색은 선택한 기준 폴더의 모든 하위 Markdown 파일명을 대상으로 합니다. 본문은 검색하지 않으며 숨김 폴더·node_modules·attachments는 탐색과 검색에서 제외됩니다. 문서가 참조하는 첨부는 미리보기·변환·업로드에서 계속 사용합니다.</p></details>
       <details><summary>폴더를 변환했는데 비교 화면에 일부만 보여요.</summary><p>본문 비교는 최대 20개 문서, 문서당 200KB까지 지원합니다. 실제 저장은 선택 폴더의 전체 변환 대상에 적용됩니다.</p></details>
       <details><summary>실행 내역의 색은 무엇을 뜻하나요?</summary><p>초록은 신규·생성·완료, 황갈색은 변경·갱신, 보라는 참조·연결, 회색은 동일·재사용입니다. 주황 배경은 경고, 빨강 배경은 오류입니다. 함께 표시된 문구로 상세 내용을 확인하세요.</p></details>
       <details><summary>새로고침하면 설정이 사라지나요?</summary><p>기준 폴더, 출력 경로, 참조 폴더와 작업 옵션은 같은 브라우저에 저장됩니다. 브라우저 데이터를 지우거나 다른 주소·포트에서 열면 설정이 다를 수 있습니다. 업로드 승인은 저장하지 않으므로 다시 미리보기하세요.</p></details>

package/dist/web/views/sync-panel.js

@@ -1,26 +1,97 @@
 export const syncPanel = `
 <div id="sync-view" class="workspace-content" role="tabpanel" aria-labelledby="tab-sync" hidden>
-  <section class="panel" aria-label="동기화 설정">
-    <div class="panel-heading"><h2><span class="section-number">02</span>Confluence 동기화</h2><span class="count">Markdown → Confluence</span></div>
-    <div class="settings-body sync-settings">
-      <p class="sync-intro">로컬 문서를 Confluence에 올립니다. 신규·변경 문서를 먼저 확인하세요.</p>
-      <div class="settings-grid">
-        <div class="field"><label for="sync-scope">동기화 범위</label><select id="sync-scope"><option value="file">선택 문서</option><option value="folder">현재 폴더</option><option value="all">기준 폴더 전체</option></select></div>
-        <div class="field"><label for="sync-env">설정 파일 <span>선택 사항</span></label><div class="path-row"><input id="sync-env" class="path-input" placeholder="기준 폴더의 .env 자동 사용"><button id="sync-load">설정 확인</button></div></div>
-      </div>
-      <div class="field"><label for="sync-references">참조 문서 폴더 <span>선택 사항 · 한 줄에 한 경로</span></label><textarea id="sync-references" class="path-input" rows="3" placeholder="다른 동기화 폴더 경로"></textarea><button id="sync-add-reference" type="button">참조 폴더 추가…</button><p class="hint">참조 폴더의 게시 매핑으로 링크를 연결합니다. 같은 Confluence 서버의 폴더를 지정하세요. 참조 문서는 업로드하지 않습니다.</p></div>
-      <p id="sync-target" class="sync-target">왼쪽에서 문서를 선택하세요.</p>
-      <p class="hint">설정 경로를 비우면 기준 폴더의 .env를 사용합니다. 없으면 웹 서버 실행 환경을 사용합니다.</p>
-      <dl id="sync-config" class="sync-config"><dt>연결 설정</dt><dd>설정 확인을 누르면 업로드 위치를 볼 수 있습니다.</dd></dl>
+  <section class="panel env-settings" aria-labelledby="sync-env-heading">
+        <div class="panel-heading"><h2 id="sync-env-heading"><button id="sync-env-toggle" class="preview-disclosure" type="button" aria-expanded="false" aria-controls="sync-env-body"><span id="sync-env-chevron" aria-hidden="true">▸</span>.env 연결 설정<span id="sync-env-toggle-label" class="preview-disclosure-label">펼치기</span></button></h2><div class="actions"><button id="sync-load" type="button">설정 확인</button><button id="sync-connect" type="button" disabled>스페이스 연결</button></div></div>
+    <div id="sync-env-body" class="env-settings-body" hidden>
+        <div class="env-help-actions"><a class="env-template-download" href="/assets/confluence-env-example.txt" download="confluence.env.example"><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v12m-5-5 5 5 5-5M4 17v4h16v-4"/></svg>.env 샘플 다운로드</a>
+        <p class="hint">API 토큰이 없나요? <button id="open-token-guide" class="quiet" type="button" aria-haspopup="dialog" aria-controls="help-dialog">API 토큰 발급 가이드</button></p></div>
+        <p class="hint">샘플의 빈 값을 채운 뒤 .env 가져오기로 선택하거나, 이름을 .env로 바꿔 기준 폴더에 저장하세요.</p>
+        <fieldset class="env-source-options"><legend class="sr-only">환경변수 설정 방식</legend>
+          <label><input type="radio" name="sync-env-source" id="sync-env-base-mode" checked><span><strong>기준 폴더의 .env 사용</strong><small>로컬 문서에서 선택한 폴더의 설정을 읽습니다.</small></span></label>
+          <label><input type="radio" name="sync-env-source" id="sync-env-import-mode"><span><strong>.env 가져오기</strong><small>파일을 선택해 현재 웹 작업에 적용합니다.</small></span></label>
+        </fieldset>
+        <div id="sync-env-import-controls" class="env-import-controls" hidden>
+          <input type="file" id="sync-env-file" hidden>
+          <div class="env-file-row"><button id="sync-env-choose" type="button">.env 파일 선택…</button><span id="sync-env-file-name">선택한 파일 없음</span></div>
+          <button id="sync-env-save" type="button" disabled>기준 폴더에 .env 저장</button>
+        </div>
+        <p id="sync-env-source-note" class="hint">로컬 문서에서 선택한 기준 폴더의 .env만 읽습니다. 파일이 없으면 .env를 가져오세요.</p>
+        <div class="env-config-summary"><h4>적용된 연결 정보</h4>
+      <dl id="sync-config" class="sync-config"><dt>연결 설정</dt><dd>설정 확인을 누르면 서버·계정·스페이스를 볼 수 있습니다.</dd></dl>
       <p id="sync-config-status" class="hint" role="status"></p>
-      <label class="repair-option"><input id="sync-verify" type="checkbox">변경 없는 문서도 Confluence 페이지 존재 확인</label>
-      <p class="hint">.confluence-syncignore와 기존 페이지 매핑을 적용합니다. 미리보기는 로컬 변경 비교이며 서버 연결·권한은 검사하지 않습니다.</p>
+        </div>
     </div>
-    <div class="action-bar"><span class="save-note">먼저 대상을 확인한 뒤 업로드하세요.</span><div class="actions"><button id="sync-preview" disabled>동기화 미리보기</button><button id="sync-push" class="primary" disabled>Confluence에 동기화</button></div></div>
-    <div class="feedback"><p id="sync-status" class="status" role="status" aria-live="polite">문서를 선택하고 동기화 미리보기를 실행하세요.</p><button id="sync-reconnect" hidden>진행 상태 다시 확인</button></div>
   </section>
-  <section class="panel sync-results" aria-label="동기화 내역">
-    <div class="panel-heading"><h2><span class="section-number">03</span>대상 및 실행 내역</h2><span id="sync-job-state" class="count">대기</span></div>
-    <div class="sync-result-body"><p id="sync-job-summary" class="hint" hidden></p><p id="sync-log-empty" class="empty">미리보기하면 문서별 신규·변경·동일 상태와 부모 계층을 확인할 수 있습니다.</p><pre id="sync-log" tabindex="0" aria-label="동기화 로그" hidden></pre></div>
+  <section class="panel sync-workbench" aria-label="Confluence 작업 설정">
+    <div class="panel-heading"><h2>Confluence</h2><span id="sync-stage-count" class="count">0개 업로드 예정</span></div>
+    <div class="sync-workbench-body">
+      <p id="sync-target" class="sync-target">로컬 문서에서 스페이스 전체를 보관할 기준 폴더를 선택하세요.</p>
+      <div class="sync-workbench-toolbar">
+        <div class="actions" aria-label="원격 변경 확인 및 가져오기">
+          <button id="sync-fetch" type="button" title="스페이스의 새 문서와 버전·위치 변경을 확인합니다. 2분 이내 결과는 재사용합니다." disabled>원격 변경 확인 (Fetch)</button>
+          <button id="sync-pull-remote" type="button" disabled>↓ 원격 변경 가져오기 (Pull)</button>
+          <label class="sync-pull-format" for="sync-pull-format">가져오기 형식<select id="sync-pull-format" aria-describedby="sync-pull-format-help"><option value="markdown">Markdown</option><option value="obsidian">Obsidian</option></select></label>
+          <button hidden id="sync-stage-scan" type="button">↻ 로컬 다시 확인</button>
+        </div>
+        <div class="actions" aria-label="업로드 대상 일괄 선택">
+          <button id="sync-stage-add" type="button" disabled><span aria-hidden="true">＋</span> 변경 문서 모두 포함</button>
+          <button id="sync-stage-remove" type="button" disabled><span aria-hidden="true">−</span> 모두 제외</button>
+        </div>
+      </div>
+      <p id="sync-pull-format-help" class="hint sync-pull-format-help">일반 Markdown 링크와 제목이 있는 인용문으로 받습니다. 이 설정은 새로 받는 문서와 복구·원복에 적용하며 기존 파일을 일괄 변환하지 않습니다.</p>
+      <div class="sync-observation"><span id="sync-stage-checking" class="stage-checking" aria-hidden="true"><i class="activity-spinner" aria-hidden="true"></i>로컬 확인 중…</span><span>로컬 자동 확인 · 5초 간격 · API 호출 없음</span><span id="sync-stage-remote-note">원격 상태 미확인 · Fetch로 갱신하세요.</span></div>
+      <div class="sync-change-heading"><h3 id="sync-stage-heading">변경사항</h3><span>받을 문서는 Pull · 보낼 변경은 체크 후 Push</span></div>
+      <p id="sync-stage-note" class="hint" role="status">로컬 변경을 자동으로 확인합니다. 원격 상태는 Fetch를 눌러 확인하세요.</p>
+      <div id="sync-stage-list" class="sync-stage-list" aria-label="업로드 문서 선택"></div>
+    </div>
+    <div class="sync-execution">
+      <div class="sync-execution-heading"><h3>선택 문서 업로드</h3><span class="count">로컬 → Confluence</span></div>
+      <p class="sync-intro">체크한 문서를 미리보기한 뒤 업로드하세요.</p>
+      <details class="sync-advanced"><summary>추가 설정 <span>참조 문서 · 원격 검증</span></summary>
+        <div class="sync-settings">
+          <div id="sync-push-options" class="sync-push-options">
+        <section class="sync-option-section" aria-labelledby="sync-reference-heading">
+          <h3 id="sync-reference-heading">참조 문서 연결 <span class="subtle-label">선택 사항</span></h3>
+          <p id="sync-references-help" class="hint">다른 동기화 폴더의 게시 매핑을 이용해 문서 링크를 연결합니다. 같은 Confluence 서버의 폴더를 지정하세요. 참조 문서는 업로드하지 않습니다.</p>
+          <div class="field"><label for="sync-references">참조 문서 폴더 <span>한 줄에 한 경로</span></label><textarea id="sync-references" class="path-input" rows="3" placeholder="다른 동기화 폴더 경로" aria-describedby="sync-references-help"></textarea></div>
+          <button id="sync-add-reference" type="button">참조 폴더 추가…</button>
+        </section>
+        <section class="sync-option-section" aria-labelledby="sync-verify-heading">
+          <h3 id="sync-verify-heading">미리보기 확인 옵션</h3>
+          <label class="repair-option sync-verify-option"><input id="sync-verify" type="checkbox" aria-describedby="sync-verify-help">Confluence의 원격 버전과 페이지 존재 여부도 확인</label>
+          <p id="sync-verify-help" class="hint">선택하면 미리보기 중 Confluence를 조회하므로 시간이 더 걸릴 수 있습니다. 파일과 원격 내용은 변경하지 않습니다.</p>
+        </section>
+      </div>
+        </div>
+      </details>
+    </div>
+    <div class="action-bar"><span class="save-note">받을 변경과 체크한 업로드 문서를 확인하세요.</span><div class="actions"><button id="sync-preview" disabled>업로드 미리보기</button><button id="sync-push" class="primary" disabled>Confluence에 업로드</button></div></div>
+    <div class="feedback"><p id="sync-status" class="status" role="status" aria-live="polite">변경사항을 확인하고 받을 문서와 보낼 문서를 선택하세요.</p><button id="sync-reconnect" hidden>진행 상태 다시 확인</button></div>
+  </section>
+
+  <dialog id="sync-diff-dialog" class="sync-diff-dialog" aria-labelledby="sync-diff-title">
+    <div class="panel-heading"><h2 id="sync-diff-title">문서 변경 비교</h2><button id="sync-diff-close" type="button">닫기</button></div>
+    <div class="settings-body"><p id="sync-diff-path" class="sync-diff-path"></p><p id="sync-diff-note" class="hint" role="status"></p>
+      <div class="actions"><button id="sync-diff-remote" type="button" hidden>원격과 비교 · 본문 1회 조회</button></div>
+      <div id="sync-diff-labels" class="sync-diff-labels" hidden><span id="sync-diff-before-label">기준 Markdown</span><span>현재 로컬 Markdown</span></div>
+      <div id="sync-diff-editor" class="sync-diff-editor" hidden></div>
+    </div>
+  </dialog>
+  <dialog id="sync-restore-dialog" class="env-confirm-dialog restore-dialog" aria-labelledby="sync-restore-title" aria-describedby="sync-restore-warning">
+    <h3 id="sync-restore-title">문서를 원격 최신으로 복구할까요?</h3>
+    <p id="sync-restore-path" class="sync-diff-path"></p>
+    <p id="sync-restore-warning" class="restore-warning"></p>
+    <p class="hint">원격 문서는 변경하지 않습니다. 복구 후 업로드 선택에서 제외합니다. 다운로드 도중 추가 수정이 생기면 중단합니다.</p>
+    <div class="actions"><button id="sync-restore-cancel" type="button">취소</button><button id="sync-restore-confirm" type="button" class="restore-confirm">원격에서 복구</button></div>
+  </dialog>
+  <dialog id="sync-env-confirm" class="env-confirm-dialog" aria-labelledby="sync-env-confirm-title">
+    <h3 id="sync-env-confirm-title">기존 .env의 연결 설정을 바꿀까요?</h3>
+    <p id="sync-env-confirm-path" class="hint"></p>
+    <p>서버 주소, 계정, API 토큰, 스페이스 키를 가져온 값으로 교체합니다. 다른 환경변수는 유지합니다.</p>
+    <div class="actions"><button id="sync-env-confirm-cancel" type="button">취소</button><button id="sync-env-confirm-save" type="button" class="primary">연결 설정 교체 후 저장</button></div>
+  </dialog>
+  <section id="sync-results" class="panel sync-results" aria-label="Confluence 작업 내역">
+    <div class="panel-heading"><h2>대상 및 실행 내역</h2><div class="actions sync-log-actions"><span id="sync-job-state" class="count sync-job-status" role="status" hidden></span><button id="sync-log-download" type="button" disabled title="현재 작업의 실행 내역을 내려받습니다. 실행 중에도 현재까지의 로그를 저장할 수 있습니다."><svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M12 3v12m-5-5 5 5 5-5M4 17v4h16v-4"/></svg>로그 다운로드</button></div></div>
+    <div class="sync-result-body"><p id="sync-job-summary" class="hint" hidden></p><p id="sync-log-empty" class="empty">미리보기하면 문서별 신규·변경·동일 상태와 부모 계층을 확인할 수 있습니다.</p><pre id="sync-log" tabindex="0" aria-label="Confluence 작업 로그" hidden></pre></div>
   </section>
 </div>`;

package/dist/web/views/token-guide.js

@@ -0,0 +1,27 @@
+/** Only annotated, account-redacted screenshots are included in the web build. */
+const steps = [
+    ['01-account-settings', '계정 설정 열기', 'Confluence 오른쪽 위 프로필 아이콘을 누른 다음 Account settings를 선택합니다.'],
+    ['02-atlassian-security', '보안 → API 토큰 관리', '상단 보안 탭에서 API 토큰 만들기 및 관리를 누릅니다. 아래 바로가기 링크로도 이동할 수 있습니다.'],
+    ['03-api-tokens', '범위를 포함한 토큰 만들기', '범위를 포함하여 API 토큰 만들기를 선택합니다.'],
+    ['04-scope-api-token-step1', '이름과 만료일 입력', 'Name에 용도를 알 수 있는 이름(예: csync)을 입력하고 만료일을 정한 뒤 다음으로 진행합니다. 스크린샷의 날짜는 예시입니다.'],
+    ['05-scope-api-token-step2', 'Confluence 앱 선택', '앱 목록에서 Confluence를 선택하고 다음을 누릅니다.'],
+    ['06-scope-api-token-step3', '필요한 권한 검색·선택', '권한 이름을 검색하고 결과 왼쪽 체크박스를 선택합니다. 필요한 권한마다 반복한 뒤 다음으로 진행합니다. 아래 표를 기준으로 선택하세요.'],
+    ['07-scope-api-token-step4', '검토 후 토큰 만들기', '이름·만료일·앱·선택한 권한을 확인하고 토큰 만들기를 누릅니다. 화면의 read:space 하나는 예시이며 csync 전체 기능에 충분하지 않습니다.'],
+];
+export const tokenGuide = `<section id="help-token"><h3>API 토큰 발급 가이드</h3>
+<p>빨간 테두리와 Click 표시를 따라 진행하세요. 계정 정보는 가려져 있습니다. API 토큰의 권한(scope)은 csync에서 처리할 로컬 파일·폴더 작업 스코프와 별개의 설정입니다.</p>
+<p><a href="https://id.atlassian.com/manage-profile/security/api-tokens" target="_blank" rel="noopener noreferrer">Atlassian API 토큰 관리 열기 ↗</a></p>
+<div class="token-guide-steps guide-steps">${steps.map(([file, title, description], i) => `<details${i === 0 ? ' open' : ''}><summary>${i + 1}. ${title}</summary><p>${description}</p><figure><a href="/assets/guide/${file}.png" target="_blank" rel="noopener noreferrer" aria-label="${i + 1}단계 이미지 원본 크기로 보기"><img src="/assets/guide/${file}.png" alt="${title}: 빨간 테두리로 표시한 조작 위치" loading="lazy"></a><figcaption>이미지를 누르면 원본 크기로 볼 수 있습니다.</figcaption></figure></details>`).join('')}</div>
+<h4>csync에서 사용하는 권한</h4>
+<p>아래 이름 전체를 검색하세요. 조회·Pull에는 기본 읽기 권한을, Push에는 필요한 쓰기 권한을 추가합니다. 토큰 계정 자체에도 대상 스페이스의 해당 권한이 있어야 합니다.</p>
+<div class="token-scope-table"><table><thead><tr><th>작업</th><th>권한</th></tr></thead><tbody>
+<tr><td>스코프 탐색·문서 조회·Pull</td><td><code>read:space:confluence</code><br><code>read:page:confluence</code><br><code>read:content-details:confluence</code></td></tr>
+<tr><td>페이지 Push</td><td><code>write:page:confluence</code></td></tr>
+<tr><td>이미지·첨부 다운로드</td><td><code>read:attachment:confluence</code></td></tr>
+<tr><td>이미지·첨부 업로드</td><td><code>read:content-details:confluence</code><br><code>write:attachment:confluence</code></td></tr>
+<tr><td>README 없는 폴더 생성</td><td><code>write:folder:confluence</code></td></tr>
+</tbody></table></div>
+<h4>발급한 토큰 적용</h4><p>생성 직후 Copy to clipboard로 복사하여 <code>.env</code>의 <code>CONFLUENCE_API_TOKEN</code>에 넣습니다. 토큰은 발급 화면을 닫은 뒤 다시 확인할 수 없습니다. 웹의 <strong>.env 가져오기</strong>로 적용하거나 기준 폴더의 <code>.env</code>를 갱신한 뒤 <strong>설정 확인</strong>을 누르세요.</p>
+<p>범위를 포함한 토큰의 <code>CONFLUENCE_BASE_URL</code>은 <code>https://api.atlassian.com/ex/confluence/&lt;CLOUD_ID&gt;/wiki</code> 형식입니다. Cloud ID는 <code>https://&lt;사이트&gt;.atlassian.net/_edge/tenant_info</code>의 <code>cloudId</code> 값입니다.</p>
+<p><a href="https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/" target="_blank" rel="noopener noreferrer">Atlassian 공식 발급 안내 ↗</a> · <a href="https://developer.atlassian.com/cloud/confluence/rest/v1/api-group-content---children-and-descendants/" target="_blank" rel="noopener noreferrer">Confluence API 권한 문서 ↗</a></p>
+</section>`;

package/dist/web/views/usage-guide.js

@@ -0,0 +1,12 @@
+const screens = [
+    { file: 'sync-workspace', title: 'Fetch·Pull과 업로드할 문서 선택', width: 1440, height: 1280,
+        description: 'Fetch로 원격 신규·변경을 확인하고 받을 문서는 Pull로 가져옵니다. 보낼 문서만 체크한 뒤 업로드 미리보기를 실행해야 업로드 버튼이 활성화됩니다.' },
+    { file: 'remote-diff', title: '원격 본문과 로컬 문서 비교', width: 1120, height: 718,
+        description: '문서 행의 diff 보기를 누르면 현재 원격 본문과 로컬 Markdown을 비교합니다. 왼쪽은 원격 HTML의 근사 변환본, 오른쪽은 로컬 본문입니다.' },
+    { file: 'document-preview', title: '문서 미리보기와 표 서식 정리', width: 1078, height: 867,
+        description: '왼쪽에서 파일을 선택하고 문서 미리보기를 펼칩니다. 문서 서식 정리에서 기본 서식이나 모든 표의 내용에 맞춤·균등 배분을 적용하고, 변경 비교 후 저장합니다.' },
+];
+export const usageGuide = `<section id="help-screens"><h3>화면으로 보기</h3>
+<p>문서와 Confluence 데이터는 사용법 설명용 예시입니다. 필요한 화면을 펼쳐 보세요.</p>
+<div class="guide-steps usage-guide-steps">${screens.map(({ file, title, description, width, height }) => `<details><summary>${title}</summary><p>${description}</p><figure><a href="/assets/guide/web/${file}.png" target="_blank" rel="noopener noreferrer" aria-label="${title} 화면 원본 크기로 보기"><img src="/assets/guide/web/${file}.png" alt="${title} 사용 화면" width="${width}" height="${height}" loading="lazy" decoding="async"></a><figcaption>이미지를 누르면 새 탭에서 원본 크기로 볼 수 있습니다.</figcaption></figure></details>`).join('')}</div>
+</section>`;