@operato/help 10.29.18 → 10.29.21

package/dist/src/components/ox-doc.d.ts

@@ -0,0 +1,34 @@
+import { LitElement, nothing, type TemplateResult } from 'lit';
+export declare class OxDoc extends LitElement {
+    /** 토픽 경로(예: "twin/concept"). 서버가 로케일 파일로 해석. */
+    topic: string;
+    /** 콘텐츠 베이스 경로(정적 파일 서빙 루트). 기본 프레임워크 help 규약. */
+    base: string;
+    /** 인라인 스폿용 — 지정 시 해당 #anchor 섹션만 노출(풀도큐먼트는 미지정). */
+    section: string;
+    /** 인라인 컴팩트 모드(패널/오버레이용 여백 축소). */
+    compact: boolean;
+    private _html;
+    private _status;
+    private _onClick;
+    /** 문서를 바꾸며 지정된 절 — 렌더가 끝난 뒤에 옮겨야 하므로 한 박자 미뤄 둔다. */
+    private _pendingAnchor;
+    /** 주소에 붙은 #절은 첫 문서를 그린 뒤 한 번만 적용한다. 이후 토픽 이동에 낡은 해시가 따라가지 않게 비운다. */
+    private _initialAnchor;
+    private _scrollToAnchor;
+    private _onLangChange;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    static styles: import("lit").CSSResult;
+    updated(changed: Map<string, unknown>): void;
+    private _load;
+    private _wrapTables;
+    /** 인라인 스폿 — id=section 인 heading 부터 다음 동급 heading 전까지만 추출(문맥 도움말용). */
+    private _sliceSection;
+    render(): TemplateResult | typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ox-doc': OxDoc;
+    }
+}

package/dist/src/components/ox-doc.js

@@ -0,0 +1,361 @@
+import { __decorate } from "tslib";
+import { LitElement, html, css } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import { i18next } from '@operato/i18n';
+/*
+ * ox-doc — ox-markdown 의 "리치 콘텐츠" 짝(peer). 범용 리치 문서 렌더러.
+ * 프레임워크 help 의 구조를 그대로 재사용: 콘텐츠 = 정적 파일(소스 아님), 로케일은 서버 라우터가 해석.
+ * 호출부는 topic 하나만 준다 → /helps/{topic}.html 을 fetch, 서버가 {topic}.{locale}.html 로 리라이트
+ * (다국어 링크 복잡함 제거). 리치 HTML 을 shadow DOM 에 렌더하고, 콘텐츠 속 범용 부품
+ * (ox-figure/ox-stage-ladder/…)은 등록 커스텀 엘리먼트로 upgrade 되어 살아난다.
+ *
+ * 세 소비자: 풀도큐먼트(그대로) · 인라인 스폿(section 앵커 하나) · AI(원문 텍스트는 소비자가 파일에서 추출).
+ *
+ * Moved here from operato-plant, -twin, -warehouse and -figure, which each kept a copy (2026-10-10).
+ * `ox-help-panel` reads the same /helps/{topic} path as markdown; whether help keeps two formats is open.
+ */
+let OxDoc = class OxDoc extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** 토픽 경로(예: "twin/concept"). 서버가 로케일 파일로 해석. */
+        this.topic = '';
+        /** 콘텐츠 베이스 경로(정적 파일 서빙 루트). 기본 프레임워크 help 규약. */
+        this.base = '/helps';
+        /** 인라인 스폿용 — 지정 시 해당 #anchor 섹션만 노출(풀도큐먼트는 미지정). */
+        this.section = '';
+        /** 인라인 컴팩트 모드(패널/오버레이용 여백 축소). */
+        this.compact = false;
+        this._html = '';
+        this._status = 'idle';
+        /*
+         * 콘텐츠 내부 토픽 링크(data-topic="twin/routing") 가로채 제자리 이동 — 앱 라우팅 무관, 자족적.
+         *
+         * 값에 앵커가 붙을 수 있다(`twin/standards-conformance#ours` = "그 문서의 그 절"). 앵커를 떼지 않으면
+         * 그대로 파일 경로가 되어 `…-conformance#ours.html` 을 받아 오려 하고, 브라우저가 `#` 뒤를 잘라
+         * 확장자 없는 주소를 요청한다 — **문서를 못 찾는다.** 실제로 세 링크가 그렇게 죽어 있었다.
+         */
+        this._onClick = (e) => {
+            var _a;
+            const link = e.composedPath().find(el => el instanceof HTMLElement && el.hasAttribute('data-topic'));
+            if (!link) {
+                const hashLink = e.composedPath().find(el => { var _a; return el instanceof HTMLAnchorElement && ((_a = el.getAttribute('href')) === null || _a === void 0 ? void 0 : _a.startsWith('#')); });
+                const hash = (_a = hashLink === null || hashLink === void 0 ? void 0 : hashLink.getAttribute('href')) === null || _a === void 0 ? void 0 : _a.slice(1);
+                if (hash) {
+                    e.preventDefault();
+                    this._scrollToAnchor(decodeURIComponent(hash));
+                }
+                return;
+            }
+            e.preventDefault();
+            const raw = link.getAttribute('data-topic');
+            if (!raw)
+                return;
+            const [topic, hash] = raw.split('#');
+            if (topic && topic !== this.topic) {
+                this._pendingAnchor = hash || '';
+                this.topic = topic;
+                // 스크롤 복귀는 호스트(스크롤 컨테이너 소유자)에 위임 — scrollIntoView 는 앱 전역을 밀어 헤더가 사라짐.
+                this.dispatchEvent(new CustomEvent('ox-doc-topic', { detail: { topic, hash: hash || '' }, bubbles: true, composed: true }));
+            }
+            else if (hash) {
+                this._scrollToAnchor(hash); // 같은 문서 안의 절로 — 문서를 다시 받아 오지 않는다
+            }
+        };
+        /** 문서를 바꾸며 지정된 절 — 렌더가 끝난 뒤에 옮겨야 하므로 한 박자 미뤄 둔다. */
+        this._pendingAnchor = '';
+        /** 주소에 붙은 #절은 첫 문서를 그린 뒤 한 번만 적용한다. 이후 토픽 이동에 낡은 해시가 따라가지 않게 비운다. */
+        this._initialAnchor = (() => {
+            try {
+                return location.hash ? decodeURIComponent(location.hash.slice(1)) : '';
+            }
+            catch (_a) {
+                return '';
+            }
+        })();
+        this._onLangChange = () => {
+            this._load();
+        };
+    }
+    /*
+     * 그 절로 옮긴다 — **가장 가까운 스크롤 조상만** 움직인다.
+     *
+     * `scrollIntoView` 를 쓰지 않는 이유: 앱 전역이 밀려 헤더가 사라진다(이 부품이 처음부터 피해 온 것).
+     * shadow 경계를 넘어 host 로 거슬러 올라가며 실제로 스크롤하는 상자를 찾고, 그 상자의 스크롤만 옮긴다.
+     */
+    _scrollToAnchor(id) {
+        var _a, _b, _c, _d, _e;
+        const el = (_b = (_a = this.renderRoot) === null || _a === void 0 ? void 0 : _a.querySelector) === null || _b === void 0 ? void 0 : _b.call(_a, `#${CSS.escape(id)}`);
+        if (!el)
+            return;
+        let cursor = this;
+        while (cursor) {
+            const next = (_c = cursor.parentElement) !== null && _c !== void 0 ? _c : (_e = (_d = cursor.getRootNode) === null || _d === void 0 ? void 0 : _d.call(cursor)) === null || _e === void 0 ? void 0 : _e.host;
+            if (!next)
+                break;
+            const st = getComputedStyle(next);
+            if (/(auto|scroll)/.test(st.overflowY) && next.scrollHeight > next.clientHeight) {
+                next.scrollTop += el.getBoundingClientRect().top - next.getBoundingClientRect().top - 12;
+                return;
+            }
+            cursor = next;
+        }
+    }
+    connectedCallback() {
+        var _a;
+        super.connectedCallback();
+        this.addEventListener('click', this._onClick);
+        (_a = i18next === null || i18next === void 0 ? void 0 : i18next.on) === null || _a === void 0 ? void 0 : _a.call(i18next, 'languageChanged', this._onLangChange);
+    }
+    disconnectedCallback() {
+        var _a;
+        super.disconnectedCallback();
+        this.removeEventListener('click', this._onClick);
+        (_a = i18next === null || i18next === void 0 ? void 0 : i18next.off) === null || _a === void 0 ? void 0 : _a.call(i18next, 'languageChanged', this._onLangChange);
+    }
+    updated(changed) {
+        if (changed.has('topic') || changed.has('base'))
+            this._load();
+        /* 새 문서가 다 그려진 뒤에야 그 절로 옮길 수 있다 — 링크에 앵커가 있었으면 여기서 처리한다. */
+        if (this._pendingAnchor && this._status === 'ready') {
+            const id = this._pendingAnchor;
+            this._pendingAnchor = '';
+            requestAnimationFrame(() => this._scrollToAnchor(id));
+        }
+    }
+    async _load() {
+        var _a;
+        if (!this.topic) {
+            this._status = 'idle';
+            this._html = '';
+            return;
+        }
+        this._status = 'loading';
+        try {
+            // 로케일은 서버 라우터가 해석(topic.html → topic.{locale}.html). 클라는 topic 만 안다.
+            // 쿠키 우선순위로 인해 en-US가 고정되는 현상을 방지하기 위해 쿼리스트링(?lng=)을 함께 전달한다.
+            const lang = (_a = i18next === null || i18next === void 0 ? void 0 : i18next.language) !== null && _a !== void 0 ? _a : 'en';
+            const res = await fetch(`${this.base}/${this.topic}.html?lng=${encodeURIComponent(lang)}`, {
+                headers: { 'accept-language': lang }
+            });
+            if (!res.ok)
+                throw new Error(`${res.status}`);
+            let content = await res.text();
+            if (this.section)
+                content = this._sliceSection(content, this.section);
+            this._html = this._wrapTables(content);
+            if (!this._pendingAnchor && this._initialAnchor) {
+                this._pendingAnchor = this._initialAnchor;
+                this._initialAnchor = '';
+            }
+            this._status = 'ready';
+        }
+        catch (e) {
+            this._status = 'error';
+            this._html = '';
+        }
+    }
+    /*
+     * 표를 가로 스크롤 상자로 감싼다 — **좁은 화면에서 표가 문서 폭을 밀어내지 않게.**
+     *
+     * 코드 블록(pre)은 이미 자기 안에서 가로로 스크롤한다. 표에는 그 장치가 없어서, 폭이 좁아지면
+     * (휴대폰·분할 화면·인라인 도움말 팝업) 비교표가 본문 바깥으로 삐져나갔다. 표는 열 수가 정해져
+     * 있어 글자만 줄여서는 들어가지 않으므로, 넘치는 쪽을 스크롤로 받는 것이 정공법이다.
+     *
+     * 문서(HTML)를 고치지 않고 렌더 시점에 감싸는 이유: 같은 파일을 세 소비자가 함께 쓴다. AI 는 태그를
+     * 걷어낸 본문을 읽으므로 표시용 래퍼가 원문에 섞이면 그쪽까지 지저분해진다.
+     */
+    _wrapTables(html) {
+        var _a;
+        if (!html.includes('<table'))
+            return html;
+        const tpl = document.createElement('template');
+        tpl.innerHTML = html;
+        for (const table of Array.from(tpl.content.querySelectorAll('table'))) {
+            if ((_a = table.parentElement) === null || _a === void 0 ? void 0 : _a.classList.contains('tablewrap'))
+                continue;
+            const wrap = document.createElement('div');
+            wrap.className = 'tablewrap';
+            table.replaceWith(wrap);
+            wrap.appendChild(table);
+        }
+        return tpl.innerHTML;
+    }
+    /** 인라인 스폿 — id=section 인 heading 부터 다음 동급 heading 전까지만 추출(문맥 도움말용). */
+    _sliceSection(full, id) {
+        const tpl = document.createElement('template');
+        tpl.innerHTML = full;
+        const anchor = tpl.content.querySelector(`#${CSS.escape(id)}`);
+        if (!anchor)
+            return full;
+        const level = anchor.tagName; // H1..H3
+        const frag = [anchor.outerHTML];
+        let n = anchor.nextElementSibling;
+        while (n && !(/^H[1-6]$/.test(n.tagName) && n.tagName <= level)) {
+            frag.push(n.outerHTML);
+            n = n.nextElementSibling;
+        }
+        return frag.join('');
+    }
+    render() {
+        var _a, _b, _c, _d;
+        if (this._status === 'loading')
+            return html `<div class="status">${(_b = (_a = i18next === null || i18next === void 0 ? void 0 : i18next.t) === null || _a === void 0 ? void 0 : _a.call(i18next, 'text.loading')) !== null && _b !== void 0 ? _b : 'Loading…'}</div>`;
+        if (this._status === 'error')
+            return html `<div class="status err">${(_d = (_c = i18next === null || i18next === void 0 ? void 0 : i18next.t) === null || _c === void 0 ? void 0 : _c.call(i18next, 'text.not found')) !== null && _d !== void 0 ? _d : 'Content not found.'} <code>${this.topic}</code></div>`;
+        if (this._status !== 'ready')
+            return html `<div class="body"><slot></slot></div>`;
+        return html `<div class="body">${unsafeHTML(this._html)}</div>`;
+    }
+};
+OxDoc.styles = css `
+    :host {
+      /* 테마 토큰 해소 순서: 호스트 오버라이드(--ox-doc-*) → 앱 토큰(--ui-*) → 리터럴 최후 폴백.
+       * 앱 안에서는 앱 테마를 그대로 따르고(모드 전환도 앱 설정에 종속), 앱 밖 단독 사용도 리터럴로 성립한다.
+       * OS 취향(prefers-color-scheme)으로 모드를 뒤집지 않는다 — 앱 설정과 어긋나 문서만 다크가 되던 결함.
+       *
+       * 가운데 층이 한때 --ink / --panel / --line 이었다. 주석에는 「앱 팔레트」라고 적혀 있었지만
+       * 그 이름을 정하는 곳이 **어디에도 없었다.** 그래서 앱 안에서도 늘 리터럴로 떨어졌고,
+       * 다크에서 제목이 검은 글자로 남아 바탕에 묻혔다. 앱의 실제 이름은 --ui-* 다
+       * (packages/shell/client/themes/ui-tokens.css). */
+      --_ink: var(--ox-doc-ink, var(--ui-ink, #16202b)); --_muted: var(--ox-doc-muted, var(--ui-muted, #566573)); --_faint: var(--ox-doc-faint, var(--ui-faint, #8a99a6));
+      --_line: var(--ox-doc-line, var(--ui-line, #dde4ea)); --_panel: var(--ox-doc-panel, var(--ui-panel, #fff)); --_ground: var(--ox-doc-ground, transparent);
+      --_accent: var(--ox-doc-accent, var(--ui-accent, #0d8f86));
+      /* 링크·강조 글자. 강조색을 본문색 쪽으로 당겨 **글자로 읽힐 만큼** 대비를 준다 —
+         라이트에서는 짙어지고 다크에서는 밝아진다. 한 식이 두 테마를 다 맡는다. */
+      --_accent-deep: var(--ox-doc-accent-deep, color-mix(in oklab, var(--_accent), var(--_ink) 22%));
+      --_accent-wash: var(--ox-doc-accent-wash, var(--ui-accent-wash, #e3f2f0));
+      /*
+       * 도판이 놓이는 **종이 면.** 테마를 따르지 않는다 — 따르면 안 된다.
+       *
+       * 그림의 잉크는 문서 파일 안에 박혀 있다(서른 편의 svg 안에 밝은 회색·짙은 남색이 1064곳).
+       * 다크에서 그 아래에 어두운 면을 깔면 선과 글자가 바탕에 묻힌다. 그래서 도판만 밝은 종이
+       * 위에 올린다 — 어두운 화면에 끼워 넣은 인쇄물처럼 읽힌다.
+       *
+       * 그림 자체가 테마를 따르게 하려면 서른 편의 svg 를 토큰으로 다시 그려야 한다. 그것은
+       * 문서를 쓰는 쪽의 일이다.
+       */
+      --_paper: var(--ox-doc-paper, #fff);
+      --_maxw: var(--ox-doc-maxw, 760px);
+      --_sans: var(--ox-doc-sans, -apple-system, BlinkMacSystemFont, "Apple SD Gothic Neo", "Pretendard", "Malgun Gothic", "Noto Sans KR", system-ui, sans-serif);
+      --_mono: var(--ox-doc-mono, "SF Mono", "JetBrains Mono", ui-monospace, Menlo, monospace);
+      display: block; color: var(--_ink); background: var(--_ground);
+      font-family: var(--_sans); line-height: 1.72; font-size: 16.5px;
+    }
+    /*
+     * ── 문서가 쓰는 이름 ────────────────────────────────────────────────────
+     * 문서(helps/*.html)는 자기 style 블록에서 --x-ink · --x-line · --x-panel · --x-wash ·
+     * --x-accent 를 쓴다. 서른 편이 모두 그렇게 적어 두었는데 **그 이름을 정하는 곳이 없었다.**
+     * 그래서 늘 리터럴(#fff · #cbd5dd)로 떨어졌고, 다크에서 문서 안의 카드와 표만 흰 조각으로
+     * 남았다.
+     *
+     * 여기서 정한다. 문서를 한 줄도 고치지 않고 서른 편이 함께 테마를 따른다.
+     */
+    .body {
+      --x-ink: var(--_ink);
+      --x-muted: var(--_muted);
+      --x-faint: var(--_faint);
+      --x-line: var(--_line);
+      --x-panel: var(--_panel);
+      --x-wash: color-mix(in oklab, var(--_line), transparent 55%);
+      --x-accent: var(--_accent);
+      /* 글자로 쓰는 강조색. 순수 강조색은 12px 라벨에서 라이트 3.79 · 다크에서도 아슬아슬하다. */
+      --x-accent-deep: var(--_accent-deep);
+    }
+    .body { max-width: var(--_maxw); margin: 0 auto; padding: var(--_pad, 10px 6px 48px); }
+    /*
+     * 한글 줄바꿈 — **낱글자 단위로 끊지 않는다.**
+     *
+     * 기본값은 한글을 어느 글자에서나 끊는다. 그래서 제목이 두 줄이 되면 "시간이 지나 / 도",
+     * "예측 시뮬레 / 이션은" 처럼 어절 중간이 어긋났다(배우기 제목 중 두 줄로 넘어가는 11개 가운데
+     * 9개가 그랬다). keep-all 은 띄어쓰기 자리에서만 끊으므로 어절이 살아남는다. 영문은 원래
+     * 띄어쓰기로 끊으므로 달라지는 것이 없다.
+     *
+     * 끊을 자리가 없는 긴 토큰(URN·식별자)은 그대로 두면 문서 폭을 밀어내므로 overflow-wrap 으로 받는다.
+     */
+    .body { word-break: keep-all; overflow-wrap: break-word; }
+    :host([compact]) .body { padding: 4px 2px 12px; font-size: 15px; }
+    /* 렌더된 콘텐츠 타이포그래피(unsafeHTML 산출물 — shadow 내부 스코프). 견본 수준 스케일·리듬. */
+    /*
+     * 조판 예외: **읽는 문서의 눈금이다.** 화면 조판(--ui-t-*)은 관리 화면의 절 제목과 표를 위한
+     * 다섯 단이라 긴 글에는 단이 모자라고, 좁은 화면에서 제목이 본문을 밀어내지 않도록 반응형이
+     * 필요하다. 그래서 clamp 로 둔다.
+     */
+    .body h1 { font-size: clamp(28px, 4.6vw, 40px); font-weight: 820; letter-spacing: -.022em; line-height: 1.16; margin: 0 0 .55em; text-wrap: balance; }
+    .body h2 { font-size: clamp(20px, 3.2vw, 26px); font-weight: 750; letter-spacing: -.017em; line-height: 1.25; margin: 2em 0 .55em; padding-top: 1em; border-top: 1px solid var(--_line); text-wrap: balance; }
+    .body h2:first-of-type { border-top: 0; padding-top: 0; }
+    .body h3 { font-size: 17px; font-weight: 680; margin: 1.4em 0 .35em; }
+    .body p { margin: 0 0 1.05em; }
+    .body h1 + p { font-size: 1.06em; color: var(--_muted); } /* 리드 문단(h1 바로 뒤) */
+    /* 히어로 아이브로우 — 펄스 점 + mono 라벨 */
+    .body .eyebrow { display: inline-flex; align-items: center; gap: 8px; font-family: var(--_mono); font-size: 12px; letter-spacing: .16em; text-transform: uppercase; color: var(--_accent-deep); font-weight: 600; margin: 0 0 14px; }
+    .body .eyebrow::before { content: ""; width: 7px; height: 7px; border-radius: 50%; background: var(--_accent); box-shadow: 0 0 0 0 var(--_accent); animation: oxpulse 2.6s infinite; }
+    @keyframes oxpulse { 0% { box-shadow: 0 0 0 0 color-mix(in oklab, var(--_accent), transparent 40%); } 70% { box-shadow: 0 0 0 9px color-mix(in oklab, var(--_accent), transparent 100%); } 100% { box-shadow: 0 0 0 0 color-mix(in oklab, var(--_accent), transparent 100%); } }
+    @media (prefers-reduced-motion: reduce) { .body .eyebrow::before { animation: none; } }
+    /* 섹션 키커 — 흐린 작은 라벨(제목 위). 섹션 구분선은 여기로 이동. */
+    /* 절 이름이다 — 문서를 훑을 때 눈이 짚는 자리. --_faint 로는 다크에서 3.64 였다(§ th 의 머리말). */
+    .body .kicker { font-family: var(--_mono); font-size: 12px; letter-spacing: .13em; text-transform: uppercase; color: var(--_muted); font-weight: 600; margin: 2.2em 0 0; padding-top: 1.1em; border-top: 1px solid var(--_line); }
+    .body .kicker + h2 { margin: .35em 0 .55em; padding-top: 0; border-top: 0; }
+    .body strong { font-weight: 700; }
+    .body em { font-style: normal; color: var(--_accent-deep); font-weight: 600; }
+    .body ul, .body ol { margin: 0 0 1.15em; padding-left: 1.35em; }
+    .body li { margin: .38em 0; }
+    .body ul li::marker { color: var(--_accent); }
+    .body ol { counter-reset: oxol; list-style: none; padding-left: 0; }
+    .body ol > li { counter-increment: oxol; position: relative; padding-left: 2.2em; }
+    .body ol > li::before { content: counter(oxol); position: absolute; left: 0; top: .05em; width: 1.55em; height: 1.55em; border-radius: 8px; background: var(--_accent-wash); color: var(--_accent-deep); font-family: var(--_mono); font-weight: 700; font-size: .82em; display: grid; place-items: center; }
+    .body a { color: var(--_accent-deep); text-underline-offset: 3px; cursor: pointer; }
+    .body a[data-topic] { text-decoration: none; font-weight: 640; }
+    .body a:hover { text-decoration: underline; }
+    .body blockquote { margin: 1.4em 0; padding: 14px 18px; border: 1px solid color-mix(in oklab, var(--_accent), transparent 68%); background: var(--_accent-wash); border-radius: 11px; color: var(--_ink); display: flex; gap: 11px; }
+    .body blockquote::before { content: "▸"; color: var(--_accent); font-weight: 700; }
+    .body blockquote p { margin: 0; }
+    .body code { font-family: var(--_mono); font-size: .86em; background: color-mix(in oklab, var(--_line), transparent 40%); padding: .12em .4em; border-radius: 5px; }
+    /* 코드 블록 — 기술 개념 문서는 실물(이벤트·설정)을 보여줘야 이해된다. 없으면 예시를 그림으로
+       모의 내게 되고, 그림은 복사도 검색도 안 된다. 긴 줄은 가로 스크롤(문서 폭을 밀지 않는다). */
+    .body pre { margin: 1.3em 0; padding: 15px 17px; background: var(--_panel); border: 1px solid var(--_line); border-radius: 11px; overflow-x: auto; font-family: var(--_mono); font-size: 12.5px; line-height: 1.62; color: var(--_ink); }
+    .body pre code { background: none; padding: 0; font-size: inherit; }
+    /* 표 = 패널 카드(견본 tiles 감) */
+    /* 표는 자기 상자 안에서 가로로 스크롤한다(_wrapTables 가 감싼다) — 좁은 화면에서 본문 폭을 밀어내지 않게. */
+    .body .tablewrap { overflow-x: auto; margin: 1.4em 0; }
+    .body .tablewrap table { margin: 0; min-width: 100%; width: auto; }
+    .body table { width: 100%; border-collapse: collapse; margin: 1.4em 0; font-size: 14px; font-variant-numeric: tabular-nums; background: var(--_panel); border: 1px solid var(--_line); border-radius: 11px; overflow: hidden; }
+    .body thead { background: color-mix(in oklab, var(--_line), transparent 55%); }
+    .body th, .body td { text-align: left; padding: 10px 13px; border-bottom: 1px solid var(--_line); }
+    .body tbody tr:last-child td { border-bottom: 0; }
+    /*
+     * 머리칸은 --_muted 다. --_faint 로 두었더니 채워진 머리행 위에서 대비가 2.8 로 떨어져
+     * 열 이름이 안 읽혔다(10.5px 글자다). --_faint 는 바탕 위의 곁말에 쓰는 색이지, 면 위에
+     * 올리는 라벨의 색이 아니다.
+     */
+    .body th { font-family: var(--_mono); font-size: 10.5px; letter-spacing: .08em; text-transform: uppercase; color: var(--_muted); font-weight: 600; }
+    .body td:first-child { font-weight: 640; }
+    .tablewrap { overflow-x: auto; }
+    /* 도판 — 테마 패널 위에 올려 라이트/다크 모드와 자연스럽게 조화되도록 한다. */
+    .body svg { display: block; max-width: 100%; box-sizing: border-box; background: var(--_panel); border: 1px solid var(--_line); border-radius: 10px; padding: 12px; }
+    .status { color: var(--_muted); font-size: 14px; padding: 24px 4px; }
+    .status.err { color: var(--ui-crit, #c0492f); }
+  `;
+__decorate([
+    property({ type: String })
+], OxDoc.prototype, "topic", void 0);
+__decorate([
+    property({ type: String })
+], OxDoc.prototype, "base", void 0);
+__decorate([
+    property({ type: String })
+], OxDoc.prototype, "section", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], OxDoc.prototype, "compact", void 0);
+__decorate([
+    state()
+], OxDoc.prototype, "_html", void 0);
+__decorate([
+    state()
+], OxDoc.prototype, "_status", void 0);
+OxDoc = __decorate([
+    customElement('ox-doc')
+], OxDoc);
+export { OxDoc };
+//# sourceMappingURL=ox-doc.js.map

package/dist/src/components/ox-doc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ox-doc.js","sourceRoot":"","sources":["../../../src/components/ox-doc.ts"],"names":[],"mappings":"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","sourcesContent":["import { LitElement, html, css, nothing, type TemplateResult } from 'lit'\nimport { customElement, property, state } from 'lit/decorators.js'\nimport { unsafeHTML } from 'lit/directives/unsafe-html.js'\nimport { i18next } from '@operato/i18n'\n\n/*\n * ox-doc — ox-markdown 의 \"리치 콘텐츠\" 짝(peer). 범용 리치 문서 렌더러.\n * 프레임워크 help 의 구조를 그대로 재사용: 콘텐츠 = 정적 파일(소스 아님), 로케일은 서버 라우터가 해석.\n * 호출부는 topic 하나만 준다 → /helps/{topic}.html 을 fetch, 서버가 {topic}.{locale}.html 로 리라이트\n * (다국어 링크 복잡함 제거). 리치 HTML 을 shadow DOM 에 렌더하고, 콘텐츠 속 범용 부품\n * (ox-figure/ox-stage-ladder/…)은 등록 커스텀 엘리먼트로 upgrade 되어 살아난다.\n *\n * 세 소비자: 풀도큐먼트(그대로) · 인라인 스폿(section 앵커 하나) · AI(원문 텍스트는 소비자가 파일에서 추출).\n *\n * Moved here from operato-plant, -twin, -warehouse and -figure, which each kept a copy (2026-10-10).\n * `ox-help-panel` reads the same /helps/{topic} path as markdown; whether help keeps two formats is open.\n */\n@customElement('ox-doc')\nexport class OxDoc extends LitElement {\n  /** 토픽 경로(예: \"twin/concept\"). 서버가 로케일 파일로 해석. */\n  @property({ type: String }) topic = ''\n  /** 콘텐츠 베이스 경로(정적 파일 서빙 루트). 기본 프레임워크 help 규약. */\n  @property({ type: String }) base = '/helps'\n  /** 인라인 스폿용 — 지정 시 해당 #anchor 섹션만 노출(풀도큐먼트는 미지정). */\n  @property({ type: String }) section = ''\n  /** 인라인 컴팩트 모드(패널/오버레이용 여백 축소). */\n  @property({ type: Boolean, reflect: true }) compact = false\n\n  @state() private _html = ''\n  @state() private _status: 'idle' | 'loading' | 'ready' | 'error' = 'idle'\n\n  /*\n   * 콘텐츠 내부 토픽 링크(data-topic=\"twin/routing\") 가로채 제자리 이동 — 앱 라우팅 무관, 자족적.\n   *\n   * 값에 앵커가 붙을 수 있다(`twin/standards-conformance#ours` = \"그 문서의 그 절\"). 앵커를 떼지 않으면\n   * 그대로 파일 경로가 되어 `…-conformance#ours.html` 을 받아 오려 하고, 브라우저가 `#` 뒤를 잘라\n   * 확장자 없는 주소를 요청한다 — **문서를 못 찾는다.** 실제로 세 링크가 그렇게 죽어 있었다.\n   */\n  private _onClick = (e: Event) => {\n    const link = e.composedPath().find(el => el instanceof HTMLElement && el.hasAttribute('data-topic')) as HTMLElement | undefined\n    if (!link) {\n      const hashLink = e.composedPath().find(el => el instanceof HTMLAnchorElement && el.getAttribute('href')?.startsWith('#')) as HTMLAnchorElement | undefined\n      const hash = hashLink?.getAttribute('href')?.slice(1)\n      if (hash) {\n        e.preventDefault()\n        this._scrollToAnchor(decodeURIComponent(hash))\n      }\n      return\n    }\n    e.preventDefault()\n    const raw = link.getAttribute('data-topic')\n    if (!raw) return\n    const [topic, hash] = raw.split('#')\n    if (topic && topic !== this.topic) {\n      this._pendingAnchor = hash || ''\n      this.topic = topic\n      // 스크롤 복귀는 호스트(스크롤 컨테이너 소유자)에 위임 — scrollIntoView 는 앱 전역을 밀어 헤더가 사라짐.\n      this.dispatchEvent(new CustomEvent('ox-doc-topic', { detail: { topic, hash: hash || '' }, bubbles: true, composed: true }))\n    } else if (hash) {\n      this._scrollToAnchor(hash) // 같은 문서 안의 절로 — 문서를 다시 받아 오지 않는다\n    }\n  }\n\n  /** 문서를 바꾸며 지정된 절 — 렌더가 끝난 뒤에 옮겨야 하므로 한 박자 미뤄 둔다. */\n  private _pendingAnchor = ''\n  /** 주소에 붙은 #절은 첫 문서를 그린 뒤 한 번만 적용한다. 이후 토픽 이동에 낡은 해시가 따라가지 않게 비운다. */\n  private _initialAnchor = (() => {\n    try { return location.hash ? decodeURIComponent(location.hash.slice(1)) : '' } catch { return '' }\n  })()\n\n  /*\n   * 그 절로 옮긴다 — **가장 가까운 스크롤 조상만** 움직인다.\n   *\n   * `scrollIntoView` 를 쓰지 않는 이유: 앱 전역이 밀려 헤더가 사라진다(이 부품이 처음부터 피해 온 것).\n   * shadow 경계를 넘어 host 로 거슬러 올라가며 실제로 스크롤하는 상자를 찾고, 그 상자의 스크롤만 옮긴다.\n   */\n  private _scrollToAnchor(id: string): void {\n    const el = this.renderRoot?.querySelector?.(`#${CSS.escape(id)}`) as HTMLElement | null\n    if (!el) return\n    let cursor: any = this\n    while (cursor) {\n      const next = cursor.parentElement ?? cursor.getRootNode?.()?.host\n      if (!next) break\n      const st = getComputedStyle(next)\n      if (/(auto|scroll)/.test(st.overflowY) && next.scrollHeight > next.clientHeight) {\n        next.scrollTop += el.getBoundingClientRect().top - next.getBoundingClientRect().top - 12\n        return\n      }\n      cursor = next\n    }\n  }\n  private _onLangChange = () => {\n    this._load()\n  }\n\n  connectedCallback() {\n    super.connectedCallback()\n    this.addEventListener('click', this._onClick)\n    i18next?.on?.('languageChanged', this._onLangChange)\n  }\n  disconnectedCallback() {\n    super.disconnectedCallback()\n    this.removeEventListener('click', this._onClick)\n    i18next?.off?.('languageChanged', this._onLangChange)\n  }\n\n  static styles = css`\n    :host {\n      /* 테마 토큰 해소 순서: 호스트 오버라이드(--ox-doc-*) → 앱 토큰(--ui-*) → 리터럴 최후 폴백.\n       * 앱 안에서는 앱 테마를 그대로 따르고(모드 전환도 앱 설정에 종속), 앱 밖 단독 사용도 리터럴로 성립한다.\n       * OS 취향(prefers-color-scheme)으로 모드를 뒤집지 않는다 — 앱 설정과 어긋나 문서만 다크가 되던 결함.\n       *\n       * 가운데 층이 한때 --ink / --panel / --line 이었다. 주석에는 「앱 팔레트」라고 적혀 있었지만\n       * 그 이름을 정하는 곳이 **어디에도 없었다.** 그래서 앱 안에서도 늘 리터럴로 떨어졌고,\n       * 다크에서 제목이 검은 글자로 남아 바탕에 묻혔다. 앱의 실제 이름은 --ui-* 다\n       * (packages/shell/client/themes/ui-tokens.css). */\n      --_ink: var(--ox-doc-ink, var(--ui-ink, #16202b)); --_muted: var(--ox-doc-muted, var(--ui-muted, #566573)); --_faint: var(--ox-doc-faint, var(--ui-faint, #8a99a6));\n      --_line: var(--ox-doc-line, var(--ui-line, #dde4ea)); --_panel: var(--ox-doc-panel, var(--ui-panel, #fff)); --_ground: var(--ox-doc-ground, transparent);\n      --_accent: var(--ox-doc-accent, var(--ui-accent, #0d8f86));\n      /* 링크·강조 글자. 강조색을 본문색 쪽으로 당겨 **글자로 읽힐 만큼** 대비를 준다 —\n         라이트에서는 짙어지고 다크에서는 밝아진다. 한 식이 두 테마를 다 맡는다. */\n      --_accent-deep: var(--ox-doc-accent-deep, color-mix(in oklab, var(--_accent), var(--_ink) 22%));\n      --_accent-wash: var(--ox-doc-accent-wash, var(--ui-accent-wash, #e3f2f0));\n      /*\n       * 도판이 놓이는 **종이 면.** 테마를 따르지 않는다 — 따르면 안 된다.\n       *\n       * 그림의 잉크는 문서 파일 안에 박혀 있다(서른 편의 svg 안에 밝은 회색·짙은 남색이 1064곳).\n       * 다크에서 그 아래에 어두운 면을 깔면 선과 글자가 바탕에 묻힌다. 그래서 도판만 밝은 종이\n       * 위에 올린다 — 어두운 화면에 끼워 넣은 인쇄물처럼 읽힌다.\n       *\n       * 그림 자체가 테마를 따르게 하려면 서른 편의 svg 를 토큰으로 다시 그려야 한다. 그것은\n       * 문서를 쓰는 쪽의 일이다.\n       */\n      --_paper: var(--ox-doc-paper, #fff);\n      --_maxw: var(--ox-doc-maxw, 760px);\n      --_sans: var(--ox-doc-sans, -apple-system, BlinkMacSystemFont, \"Apple SD Gothic Neo\", \"Pretendard\", \"Malgun Gothic\", \"Noto Sans KR\", system-ui, sans-serif);\n      --_mono: var(--ox-doc-mono, \"SF Mono\", \"JetBrains Mono\", ui-monospace, Menlo, monospace);\n      display: block; color: var(--_ink); background: var(--_ground);\n      font-family: var(--_sans); line-height: 1.72; font-size: 16.5px;\n    }\n    /*\n     * ── 문서가 쓰는 이름 ────────────────────────────────────────────────────\n     * 문서(helps/*.html)는 자기 style 블록에서 --x-ink · --x-line · --x-panel · --x-wash ·\n     * --x-accent 를 쓴다. 서른 편이 모두 그렇게 적어 두었는데 **그 이름을 정하는 곳이 없었다.**\n     * 그래서 늘 리터럴(#fff · #cbd5dd)로 떨어졌고, 다크에서 문서 안의 카드와 표만 흰 조각으로\n     * 남았다.\n     *\n     * 여기서 정한다. 문서를 한 줄도 고치지 않고 서른 편이 함께 테마를 따른다.\n     */\n    .body {\n      --x-ink: var(--_ink);\n      --x-muted: var(--_muted);\n      --x-faint: var(--_faint);\n      --x-line: var(--_line);\n      --x-panel: var(--_panel);\n      --x-wash: color-mix(in oklab, var(--_line), transparent 55%);\n      --x-accent: var(--_accent);\n      /* 글자로 쓰는 강조색. 순수 강조색은 12px 라벨에서 라이트 3.79 · 다크에서도 아슬아슬하다. */\n      --x-accent-deep: var(--_accent-deep);\n    }\n    .body { max-width: var(--_maxw); margin: 0 auto; padding: var(--_pad, 10px 6px 48px); }\n    /*\n     * 한글 줄바꿈 — **낱글자 단위로 끊지 않는다.**\n     *\n     * 기본값은 한글을 어느 글자에서나 끊는다. 그래서 제목이 두 줄이 되면 \"시간이 지나 / 도\",\n     * \"예측 시뮬레 / 이션은\" 처럼 어절 중간이 어긋났다(배우기 제목 중 두 줄로 넘어가는 11개 가운데\n     * 9개가 그랬다). keep-all 은 띄어쓰기 자리에서만 끊으므로 어절이 살아남는다. 영문은 원래\n     * 띄어쓰기로 끊으므로 달라지는 것이 없다.\n     *\n     * 끊을 자리가 없는 긴 토큰(URN·식별자)은 그대로 두면 문서 폭을 밀어내므로 overflow-wrap 으로 받는다.\n     */\n    .body { word-break: keep-all; overflow-wrap: break-word; }\n    :host([compact]) .body { padding: 4px 2px 12px; font-size: 15px; }\n    /* 렌더된 콘텐츠 타이포그래피(unsafeHTML 산출물 — shadow 내부 스코프). 견본 수준 스케일·리듬. */\n    /*\n     * 조판 예외: **읽는 문서의 눈금이다.** 화면 조판(--ui-t-*)은 관리 화면의 절 제목과 표를 위한\n     * 다섯 단이라 긴 글에는 단이 모자라고, 좁은 화면에서 제목이 본문을 밀어내지 않도록 반응형이\n     * 필요하다. 그래서 clamp 로 둔다.\n     */\n    .body h1 { font-size: clamp(28px, 4.6vw, 40px); font-weight: 820; letter-spacing: -.022em; line-height: 1.16; margin: 0 0 .55em; text-wrap: balance; }\n    .body h2 { font-size: clamp(20px, 3.2vw, 26px); font-weight: 750; letter-spacing: -.017em; line-height: 1.25; margin: 2em 0 .55em; padding-top: 1em; border-top: 1px solid var(--_line); text-wrap: balance; }\n    .body h2:first-of-type { border-top: 0; padding-top: 0; }\n    .body h3 { font-size: 17px; font-weight: 680; margin: 1.4em 0 .35em; }\n    .body p { margin: 0 0 1.05em; }\n    .body h1 + p { font-size: 1.06em; color: var(--_muted); } /* 리드 문단(h1 바로 뒤) */\n    /* 히어로 아이브로우 — 펄스 점 + mono 라벨 */\n    .body .eyebrow { display: inline-flex; align-items: center; gap: 8px; font-family: var(--_mono); font-size: 12px; letter-spacing: .16em; text-transform: uppercase; color: var(--_accent-deep); font-weight: 600; margin: 0 0 14px; }\n    .body .eyebrow::before { content: \"\"; width: 7px; height: 7px; border-radius: 50%; background: var(--_accent); box-shadow: 0 0 0 0 var(--_accent); animation: oxpulse 2.6s infinite; }\n    @keyframes oxpulse { 0% { box-shadow: 0 0 0 0 color-mix(in oklab, var(--_accent), transparent 40%); } 70% { box-shadow: 0 0 0 9px color-mix(in oklab, var(--_accent), transparent 100%); } 100% { box-shadow: 0 0 0 0 color-mix(in oklab, var(--_accent), transparent 100%); } }\n    @media (prefers-reduced-motion: reduce) { .body .eyebrow::before { animation: none; } }\n    /* 섹션 키커 — 흐린 작은 라벨(제목 위). 섹션 구분선은 여기로 이동. */\n    /* 절 이름이다 — 문서를 훑을 때 눈이 짚는 자리. --_faint 로는 다크에서 3.64 였다(§ th 의 머리말). */\n    .body .kicker { font-family: var(--_mono); font-size: 12px; letter-spacing: .13em; text-transform: uppercase; color: var(--_muted); font-weight: 600; margin: 2.2em 0 0; padding-top: 1.1em; border-top: 1px solid var(--_line); }\n    .body .kicker + h2 { margin: .35em 0 .55em; padding-top: 0; border-top: 0; }\n    .body strong { font-weight: 700; }\n    .body em { font-style: normal; color: var(--_accent-deep); font-weight: 600; }\n    .body ul, .body ol { margin: 0 0 1.15em; padding-left: 1.35em; }\n    .body li { margin: .38em 0; }\n    .body ul li::marker { color: var(--_accent); }\n    .body ol { counter-reset: oxol; list-style: none; padding-left: 0; }\n    .body ol > li { counter-increment: oxol; position: relative; padding-left: 2.2em; }\n    .body ol > li::before { content: counter(oxol); position: absolute; left: 0; top: .05em; width: 1.55em; height: 1.55em; border-radius: 8px; background: var(--_accent-wash); color: var(--_accent-deep); font-family: var(--_mono); font-weight: 700; font-size: .82em; display: grid; place-items: center; }\n    .body a { color: var(--_accent-deep); text-underline-offset: 3px; cursor: pointer; }\n    .body a[data-topic] { text-decoration: none; font-weight: 640; }\n    .body a:hover { text-decoration: underline; }\n    .body blockquote { margin: 1.4em 0; padding: 14px 18px; border: 1px solid color-mix(in oklab, var(--_accent), transparent 68%); background: var(--_accent-wash); border-radius: 11px; color: var(--_ink); display: flex; gap: 11px; }\n    .body blockquote::before { content: \"▸\"; color: var(--_accent); font-weight: 700; }\n    .body blockquote p { margin: 0; }\n    .body code { font-family: var(--_mono); font-size: .86em; background: color-mix(in oklab, var(--_line), transparent 40%); padding: .12em .4em; border-radius: 5px; }\n    /* 코드 블록 — 기술 개념 문서는 실물(이벤트·설정)을 보여줘야 이해된다. 없으면 예시를 그림으로\n       모의 내게 되고, 그림은 복사도 검색도 안 된다. 긴 줄은 가로 스크롤(문서 폭을 밀지 않는다). */\n    .body pre { margin: 1.3em 0; padding: 15px 17px; background: var(--_panel); border: 1px solid var(--_line); border-radius: 11px; overflow-x: auto; font-family: var(--_mono); font-size: 12.5px; line-height: 1.62; color: var(--_ink); }\n    .body pre code { background: none; padding: 0; font-size: inherit; }\n    /* 표 = 패널 카드(견본 tiles 감) */\n    /* 표는 자기 상자 안에서 가로로 스크롤한다(_wrapTables 가 감싼다) — 좁은 화면에서 본문 폭을 밀어내지 않게. */\n    .body .tablewrap { overflow-x: auto; margin: 1.4em 0; }\n    .body .tablewrap table { margin: 0; min-width: 100%; width: auto; }\n    .body table { width: 100%; border-collapse: collapse; margin: 1.4em 0; font-size: 14px; font-variant-numeric: tabular-nums; background: var(--_panel); border: 1px solid var(--_line); border-radius: 11px; overflow: hidden; }\n    .body thead { background: color-mix(in oklab, var(--_line), transparent 55%); }\n    .body th, .body td { text-align: left; padding: 10px 13px; border-bottom: 1px solid var(--_line); }\n    .body tbody tr:last-child td { border-bottom: 0; }\n    /*\n     * 머리칸은 --_muted 다. --_faint 로 두었더니 채워진 머리행 위에서 대비가 2.8 로 떨어져\n     * 열 이름이 안 읽혔다(10.5px 글자다). --_faint 는 바탕 위의 곁말에 쓰는 색이지, 면 위에\n     * 올리는 라벨의 색이 아니다.\n     */\n    .body th { font-family: var(--_mono); font-size: 10.5px; letter-spacing: .08em; text-transform: uppercase; color: var(--_muted); font-weight: 600; }\n    .body td:first-child { font-weight: 640; }\n    .tablewrap { overflow-x: auto; }\n    /* 도판 — 테마 패널 위에 올려 라이트/다크 모드와 자연스럽게 조화되도록 한다. */\n    .body svg { display: block; max-width: 100%; box-sizing: border-box; background: var(--_panel); border: 1px solid var(--_line); border-radius: 10px; padding: 12px; }\n    .status { color: var(--_muted); font-size: 14px; padding: 24px 4px; }\n    .status.err { color: var(--ui-crit, #c0492f); }\n  `\n\n  updated(changed: Map<string, unknown>) {\n    if (changed.has('topic') || changed.has('base')) this._load()\n    /* 새 문서가 다 그려진 뒤에야 그 절로 옮길 수 있다 — 링크에 앵커가 있었으면 여기서 처리한다. */\n    if (this._pendingAnchor && this._status === 'ready') {\n      const id = this._pendingAnchor\n      this._pendingAnchor = ''\n      requestAnimationFrame(() => this._scrollToAnchor(id))\n    }\n  }\n\n  private async _load() {\n    if (!this.topic) { this._status = 'idle'; this._html = ''; return }\n    this._status = 'loading'\n    try {\n      // 로케일은 서버 라우터가 해석(topic.html → topic.{locale}.html). 클라는 topic 만 안다.\n      // 쿠키 우선순위로 인해 en-US가 고정되는 현상을 방지하기 위해 쿼리스트링(?lng=)을 함께 전달한다.\n      const lang = i18next?.language ?? 'en'\n      const res = await fetch(`${this.base}/${this.topic}.html?lng=${encodeURIComponent(lang)}`, {\n        headers: { 'accept-language': lang }\n      })\n      if (!res.ok) throw new Error(`${res.status}`)\n      let content = await res.text()\n      if (this.section) content = this._sliceSection(content, this.section)\n      this._html = this._wrapTables(content)\n      if (!this._pendingAnchor && this._initialAnchor) {\n        this._pendingAnchor = this._initialAnchor\n        this._initialAnchor = ''\n      }\n      this._status = 'ready'\n    } catch (e) {\n      this._status = 'error'\n      this._html = ''\n    }\n  }\n\n  /*\n   * 표를 가로 스크롤 상자로 감싼다 — **좁은 화면에서 표가 문서 폭을 밀어내지 않게.**\n   *\n   * 코드 블록(pre)은 이미 자기 안에서 가로로 스크롤한다. 표에는 그 장치가 없어서, 폭이 좁아지면\n   * (휴대폰·분할 화면·인라인 도움말 팝업) 비교표가 본문 바깥으로 삐져나갔다. 표는 열 수가 정해져\n   * 있어 글자만 줄여서는 들어가지 않으므로, 넘치는 쪽을 스크롤로 받는 것이 정공법이다.\n   *\n   * 문서(HTML)를 고치지 않고 렌더 시점에 감싸는 이유: 같은 파일을 세 소비자가 함께 쓴다. AI 는 태그를\n   * 걷어낸 본문을 읽으므로 표시용 래퍼가 원문에 섞이면 그쪽까지 지저분해진다.\n   */\n  private _wrapTables(html: string): string {\n    if (!html.includes('<table')) return html\n    const tpl = document.createElement('template')\n    tpl.innerHTML = html\n    for (const table of Array.from(tpl.content.querySelectorAll('table'))) {\n      if ((table.parentElement as HTMLElement | null)?.classList.contains('tablewrap')) continue\n      const wrap = document.createElement('div')\n      wrap.className = 'tablewrap'\n      table.replaceWith(wrap)\n      wrap.appendChild(table)\n    }\n    return tpl.innerHTML\n  }\n\n  /** 인라인 스폿 — id=section 인 heading 부터 다음 동급 heading 전까지만 추출(문맥 도움말용). */\n  private _sliceSection(full: string, id: string): string {\n    const tpl = document.createElement('template')\n    tpl.innerHTML = full\n    const anchor = tpl.content.querySelector(`#${CSS.escape(id)}`)\n    if (!anchor) return full\n    const level = anchor.tagName // H1..H3\n    const frag: string[] = [(anchor as HTMLElement).outerHTML]\n    let n = anchor.nextElementSibling\n    while (n && !(/^H[1-6]$/.test(n.tagName) && n.tagName <= level)) { frag.push((n as HTMLElement).outerHTML); n = n.nextElementSibling }\n    return frag.join('')\n  }\n\n  render(): TemplateResult | typeof nothing {\n    if (this._status === 'loading') return html`<div class=\"status\">${i18next?.t?.('text.loading') ?? 'Loading…'}</div>`\n    if (this._status === 'error') return html`<div class=\"status err\">${i18next?.t?.('text.not found') ?? 'Content not found.'} <code>${this.topic}</code></div>`\n    if (this._status !== 'ready') return html`<div class=\"body\"><slot></slot></div>`\n    return html`<div class=\"body\">${unsafeHTML(this._html)}</div>`\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap { 'ox-doc': OxDoc }\n}\n"]}

package/dist/src/components/ox-figure.d.ts

@@ -0,0 +1,14 @@
+import { LitElement, type TemplateResult } from 'lit';
+export declare class OxFigure extends LitElement {
+    /** 캡션(선택). slot="caption" 으로 리치 캡션도 가능. */
+    caption: string;
+    /** 강조 테두리(핵심 시각물). */
+    featured: boolean;
+    static styles: import("lit").CSSResult;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ox-figure': OxFigure;
+    }
+}

package/dist/src/components/ox-figure.js

@@ -0,0 +1,51 @@
+import { __decorate } from "tslib";
+import { LitElement, html, css } from 'lit';
+import { customElement, property } from 'lit/decorators.js';
+/*
+ * ox-figure — 범용 그림/다이어그램 컨테이너(도메인 무관). 리치 문서의 시각물을 감싸고 캡션을 붙인다.
+ * 콘텐츠(SVG/img/커스텀 시각물)는 slot 으로 받으므로, 컴포넌트 미등록 시에도 그대로 노출(폴백 안전).
+ */
+let OxFigure = class OxFigure extends LitElement {
+    constructor() {
+        super(...arguments);
+        /** 캡션(선택). slot="caption" 으로 리치 캡션도 가능. */
+        this.caption = '';
+        /** 강조 테두리(핵심 시각물). */
+        this.featured = false;
+    }
+    render() {
+        return html `
+      <figure>
+        <div class="slot"><slot></slot></div>
+        ${this.caption ? html `<figcaption>${this.caption}</figcaption>` : html `<figcaption><slot name="caption"></slot></figcaption>`}
+      </figure>
+    `;
+    }
+};
+OxFigure.styles = css `
+    :host {
+      /* 해소 순서: 호스트 오버라이드 → 앱 팔레트 → 리터럴(ox-doc 와 동일 규약). */
+      --_line: var(--ox-doc-line, var(--ui-line, #dde4ea)); --_panel: var(--ox-doc-panel, var(--ui-panel, #fff)); --_muted: var(--ox-doc-muted, var(--ui-muted, #566573));
+      --_accent: var(--ox-doc-accent, var(--ui-accent, #0d8f86));
+      --_mono: var(--ox-doc-mono, "SF Mono", ui-monospace, Menlo, monospace);
+      display: block; margin: 20px 0;
+    }
+    figure { margin: 0; background: var(--_panel); border: 1px solid var(--_line); border-radius: 14px; padding: 20px; }
+    :host([featured]) figure { border-color: color-mix(in oklab, var(--_accent), var(--_line) 55%); box-shadow: 0 8px 30px rgba(22,32,43,.06); }
+    .slot { display: block; }
+    /* 도판은 종이 위에 — 그림의 잉크가 파일 안에 박혀 있어 어두운 면 위에서는 묻힌다(ox-doc 의 --_paper). */
+    ::slotted(svg), ::slotted(img) { display: block; width: 100%; height: auto; box-sizing: border-box; background: var(--ox-doc-paper, #fff); border-radius: 8px; }
+    /* 캡션은 그림이 무엇인지 말하는 유일한 글자다 — 곁말이 아니라 읽히는 값으로 둔다. */
+    figcaption { margin-top: 12px; text-align: center; font-family: var(--_mono); font-size: 12.5px; color: var(--_muted); letter-spacing: .02em; line-height: 1.5; }
+  `;
+__decorate([
+    property({ type: String })
+], OxFigure.prototype, "caption", void 0);
+__decorate([
+    property({ type: Boolean })
+], OxFigure.prototype, "featured", void 0);
+OxFigure = __decorate([
+    customElement('ox-figure')
+], OxFigure);
+export { OxFigure };
+//# sourceMappingURL=ox-figure.js.map

package/dist/src/components/ox-figure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ox-figure.js","sourceRoot":"","sources":["../../../src/components/ox-figure.ts"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,EAAuB,MAAM,KAAK,CAAA;AAChE,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE3D;;;GAGG;AAEI,IAAM,QAAQ,GAAd,MAAM,QAAS,SAAQ,UAAU;IAAjC;;QACL,2CAA2C;QACf,YAAO,GAAG,EAAE,CAAA;QACxC,sBAAsB;QACO,aAAQ,GAAG,KAAK,CAAA;IA2B/C,CAAC;IARC,MAAM;QACJ,OAAO,IAAI,CAAA;;;UAGL,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAA,eAAe,IAAI,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,IAAI,CAAA,uDAAuD;;KAEhI,CAAA;IACH,CAAC;;AAxBM,eAAM,GAAG,GAAG,CAAA;;;;;;;;;;;;;;;GAelB,AAfY,CAeZ;AAnB2B;IAA3B,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;yCAAa;AAEX;IAA5B,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;0CAAiB;AAJlC,QAAQ;IADpB,aAAa,CAAC,WAAW,CAAC;GACd,QAAQ,CA+BpB","sourcesContent":["import { LitElement, html, css, type TemplateResult } from 'lit'\nimport { customElement, property } from 'lit/decorators.js'\n\n/*\n * ox-figure — 범용 그림/다이어그램 컨테이너(도메인 무관). 리치 문서의 시각물을 감싸고 캡션을 붙인다.\n * 콘텐츠(SVG/img/커스텀 시각물)는 slot 으로 받으므로, 컴포넌트 미등록 시에도 그대로 노출(폴백 안전).\n */\n@customElement('ox-figure')\nexport class OxFigure extends LitElement {\n  /** 캡션(선택). slot=\"caption\" 으로 리치 캡션도 가능. */\n  @property({ type: String }) caption = ''\n  /** 강조 테두리(핵심 시각물). */\n  @property({ type: Boolean }) featured = false\n\n  static styles = css`\n    :host {\n      /* 해소 순서: 호스트 오버라이드 → 앱 팔레트 → 리터럴(ox-doc 와 동일 규약). */\n      --_line: var(--ox-doc-line, var(--ui-line, #dde4ea)); --_panel: var(--ox-doc-panel, var(--ui-panel, #fff)); --_muted: var(--ox-doc-muted, var(--ui-muted, #566573));\n      --_accent: var(--ox-doc-accent, var(--ui-accent, #0d8f86));\n      --_mono: var(--ox-doc-mono, \"SF Mono\", ui-monospace, Menlo, monospace);\n      display: block; margin: 20px 0;\n    }\n    figure { margin: 0; background: var(--_panel); border: 1px solid var(--_line); border-radius: 14px; padding: 20px; }\n    :host([featured]) figure { border-color: color-mix(in oklab, var(--_accent), var(--_line) 55%); box-shadow: 0 8px 30px rgba(22,32,43,.06); }\n    .slot { display: block; }\n    /* 도판은 종이 위에 — 그림의 잉크가 파일 안에 박혀 있어 어두운 면 위에서는 묻힌다(ox-doc 의 --_paper). */\n    ::slotted(svg), ::slotted(img) { display: block; width: 100%; height: auto; box-sizing: border-box; background: var(--ox-doc-paper, #fff); border-radius: 8px; }\n    /* 캡션은 그림이 무엇인지 말하는 유일한 글자다 — 곁말이 아니라 읽히는 값으로 둔다. */\n    figcaption { margin-top: 12px; text-align: center; font-family: var(--_mono); font-size: 12.5px; color: var(--_muted); letter-spacing: .02em; line-height: 1.5; }\n  `\n\n  render(): TemplateResult {\n    return html`\n      <figure>\n        <div class=\"slot\"><slot></slot></div>\n        ${this.caption ? html`<figcaption>${this.caption}</figcaption>` : html`<figcaption><slot name=\"caption\"></slot></figcaption>`}\n      </figure>\n    `\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap { 'ox-figure': OxFigure }\n}\n"]}

package/dist/src/components/ox-help-spot.d.ts

@@ -0,0 +1,27 @@
+import { LitElement, type TemplateResult } from 'lit';
+import './ox-doc.js';
+export declare class OxHelpSpot extends LitElement {
+    topic: string;
+    section: string;
+    label: string;
+    private open;
+    static styles: import("lit").CSSResult;
+    private toggle;
+    private close;
+    private openFull;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * `Escape` 로 닫는다 — **뒷막 누름의 키보드 짝**이다.
+     *
+     * 이것이 없으면 도움말을 연 사람이 탭으로 그 안을 다 지나야 빠져나온다. 마우스로 열어 보면 안
+     * 보이는 부류다(WCAG 2.1 §2.1.1 · §2.1.2).
+     */
+    private readonly onKeydown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'ox-help-spot': OxHelpSpot;
+    }
+}