@dybai/file-line-reference 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dy.bai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# 文件行引用 · File Line Reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness (DSH) 插件：在侧栏文件预览中选中若干行，把 `@路径:起-止` 行范围引用插入对话输入框；点击消息里的引用 chip 直接跳回文件的起始行。
+
+- 划选拖拽或行选模式（点击选中、Shift 连选、Ctrl/Cmd 增减）→ 工具栏按钮或 **Ctrl+Shift+L** 插入引用到草稿；
+- 引用前后自动补空格，不会与相邻文字粘连；
+- 纯文本预览可开关行号（代码预览自带行号），屏上所见即所选；
+- 全局快捷键默认 `Ctrl+Shift+L`（macOS `⌘⇧L`），可在 设置 → 快捷键 中改键（命令：文件行引用 → 添加选中行到对话）。
+
+## 安装
+
+见 [docs/deploy.zh-CN.md](docs/deploy.zh-CN.md) 第 5 节：启用实验性插件市场后添加本仓库的索引 URL，或直接按 spec 安装。
+
+## 开发与发布
+
+```powershell
+node scripts/build.mjs         # src/ 变更后重新生成 client.js
+node --test                    # 纯逻辑单测
+node scripts/verify-loader.mjs # DSH ModuleLoader 契约模拟
+```
+
+编译、发布（git/npm 两种模式）与常见坑的完整手册：[docs/deploy.zh-CN.md](docs/deploy.zh-CN.md)。
+
+## License
+
+[MIT](LICENSE)

package/client.js

@@ -0,0 +1,849 @@
+/* Generated by scripts/build.mjs from src/ — do not edit. */
+window.__ModuleLoader__.load({
+	id: '@dybai/file-line-reference',
+	factory(require) {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		const FlrCore = (function () {
+
+	/** The shared file-reference token grammar: quoted `@"…"` or a `@`-run of non-space, at a whitespace boundary. */
+	const TOKEN_SOURCE = '(?<!\\S)(@"[^"\\n]+"|@[^\\s]+)';
+	const TRAILING_PUNCTUATION = /[.,;:!?，。；：！？]+$/u;
+	const LINE_SUFFIX = /^(\d{1,7})(?:-(\d{1,7}))?$/u;
+	const FILE_ADDRESS_PREFIX = 'dsh-resource://file/';
+
+	/** Remove trailing punctuation the reference grammar treats as sentence text. */
+	function stripTrailingPunctuation(text) {
+		return text.replace(TRAILING_PUNCTUATION, '');
+	}
+
+	/**
+	 * Split a trailing `:S-E` / `:S` line suffix off a path at the last colon.
+	 * @param path - candidate path text, quotes already removed.
+	 * @returns `{ path, start, end }` with 1-based inclusive lines, or null.
+	 */
+	function parseLineSuffix(path) {
+		if (typeof path !== 'string') return null;
+		const colon = path.lastIndexOf(':');
+		if (colon <= 0) return null;
+		const suffix = path.slice(colon + 1);
+		const match = LINE_SUFFIX.exec(suffix);
+		if (match === null) return null;
+		const filePath = path.slice(0, colon);
+		if (filePath.length === 0 || filePath.endsWith('/')) return null;
+		const start = Number(match[1]);
+		const end = match[2] === undefined ? start : Number(match[2]);
+		if (!Number.isSafeInteger(start) || start < 1) return null;
+		if (!Number.isSafeInteger(end) || end < start) return null;
+		return { path: filePath, start, end };
+	}
+
+	/** Display label of a path: its last non-empty segment in either separator spelling. */
+	function labelOf(path) {
+		return path.split(/[\\/]/u).filter(Boolean).at(-1) ?? path;
+	}
+
+	/**
+	 * Find the nearest `@path:S-E` token at or after `from`.
+	 * @param text - the complete original text; never mutated.
+	 * @param from - inclusive UTF-16 offset to search from.
+	 * @returns a `file-lines` user-text node, or `undefined` when no later
+	 * candidate exists. The conversation pipeline treats only `undefined` as
+	 * "no match" — returning `null` would crash its `node.start` access.
+	 */
+	function matchFileLinesNode(text, from) {
+		const re = new RegExp(TOKEN_SOURCE, 'gu');
+		re.lastIndex = from;
+		for (let match = re.exec(text); match !== null; match = re.exec(text)) {
+			const token = match[0];
+			const quoted = token.startsWith('@"');
+			const raw = quoted ? token : stripTrailingPunctuation(token);
+			if (raw.length <= 1) continue;
+			const inner = quoted ? raw.slice(2, -1) : raw.slice(1);
+			const parsed = parseLineSuffix(inner);
+			if (parsed === null) continue;
+			return {
+				id: 'file-lines',
+				start: match.index,
+				end: match.index + raw.length,
+				data: {
+					path: parsed.path,
+					label: labelOf(parsed.path),
+					lineStart: parsed.start,
+					lineEnd: parsed.end,
+					raw
+				}
+			};
+		}
+		return undefined;
+	}
+
+	/**
+	 * Fold 1-based line numbers into ascending contiguous inclusive runs.
+	 * @param numbers - arbitrary-order line numbers; duplicates and stray values ignored.
+	 * @returns `[start, end]` pairs, contiguous runs merged.
+	 */
+	function mergeLines(numbers) {
+		const sorted = [...new Set(numbers)]
+			.filter((n) => Number.isInteger(n) && n >= 1)
+			.sort((left, right) => left - right);
+		const runs = [];
+		for (const n of sorted) {
+			const last = runs[runs.length - 1];
+			if (last !== undefined && n === last[1] + 1) last[1] = n;
+			else runs.push([n, n]);
+		}
+		return runs;
+	}
+
+	/**
+	 * Build mention text for one path and line runs, quoting paths the unquoted
+	 * grammar cannot represent (whitespace); control characters or quotes in the
+	 * path are unrepresentable and answer the empty string.
+	 * @param path - workspace-relative or absolute path in either separator spelling.
+	 * @param ranges - ascending `[start, end]` inclusive line runs.
+	 * @returns space-joined `@path:S-E` mentions, or '' when nothing is representable.
+	 */
+	function formatMention(path, ranges) {
+		if (typeof path !== 'string' || path.length === 0) return '';
+		const runs = (ranges ?? []).filter(([s, e]) => Number.isSafeInteger(s) && s >= 1 && Number.isSafeInteger(e) && e >= s);
+		if (runs.length === 0) return '';
+		if (/["\u0000-\u001f\u007f-\u009f]/u.test(path)) return '';
+		const quoted = /\s/u.test(path);
+		return runs
+			.map(([s, e]) => {
+				const ref = `${path}:${s === e ? `${s}` : `${s}-${e}`}`;
+				return quoted ? `@"${ref}"` : `@${ref}`;
+			})
+			.join(' ');
+	}
+
+	/**
+	 * Normalize a path for a mention: forward slashes, and the session cwd
+	 * stripped when the path lives inside it (comparison is case-insensitive for
+	 * Windows spellings); anything else stays absolute.
+	 */
+	function relativeMentionPath(path, cwd) {
+		const normalized = String(path).replace(/\\/g, '/');
+		if (cwd === undefined || cwd === null || cwd === '') return normalized;
+		const root = String(cwd).replace(/\\/g, '/').replace(/\/+$/, '');
+		if (root === '') return normalized;
+		if (normalized.toLowerCase() === root.toLowerCase()) return '';
+		if (normalized.toLowerCase().startsWith(`${root.toLowerCase()}/`)) return normalized.slice(root.length + 1);
+		return normalized;
+	}
+
+	/** Component-encode one address segment, keeping `:` literal for drive letters. */
+	function encodeSegment(segment) {
+		return encodeURIComponent(segment).replace(/%3A/gi, ':');
+	}
+
+	/** Encode a `/`-separated path segment by segment. */
+	function encodePath(path) {
+		return path.split('/').map(encodeSegment).join('/');
+	}
+
+	/** Build the `dsh-resource://file/session/<id>/<path>` address of a normalized path. */
+	function sessionFileAddress(sessionId, path) {
+		const normalized = path.replace(/\\/g, '/').replace(/^(?:\.\/)+/, '');
+		return `${FILE_ADDRESS_PREFIX}session/${encodeSegment(sessionId)}/${encodePath(normalized)}`;
+	}
+
+	/** Whether a path is absolute in either spelling the Host accepts. */
+	function isAbsoluteWorkspacePath(path) {
+		return path.startsWith('/') || /^[A-Za-z]:[/\\]/u.test(path) || path.startsWith('\\\\');
+	}
+
+	/**
+	 * The address for a path as a caller holds it: relative or inside the
+	 * Session's workspace becomes session-relative; anything else keeps its
+	 * absolute path inside that Session's address.
+	 */
+	function fileAddress(sessionId, cwd, path) {
+		const normalized = path.replace(/\\/g, '/');
+		if (!isAbsoluteWorkspacePath(normalized)) return sessionFileAddress(sessionId, normalized);
+		const root = cwd === undefined || cwd === null ? '' : String(cwd).replace(/\\/g, '/').replace(/\/+$/, '');
+		if (root !== '' && normalized === root) return sessionFileAddress(sessionId, '');
+		if (root !== '' && normalized.startsWith(`${root}/`)) return sessionFileAddress(sessionId, normalized.slice(root.length + 1));
+		return sessionFileAddress(sessionId, normalized);
+	}
+
+	/**
+	 * Pad one draft insertion with spaces so the mention never glues to
+	 * neighboring text: a leading space unless the caret sits at offset 0 or
+	 * after whitespace; a trailing space unless whitespace immediately follows —
+	 * at the draft end the trailing space always lands, so text typed next
+	 * cannot be swallowed into the reference path.
+	 *
+	 * Callers that pass an empty draft with a live span start (the conservative
+	 * retry path) get exactly this always-pad shape: `draft[start - 1]` is
+	 * `undefined`, which never counts as whitespace, so the leading space lands
+	 * whenever `start > 0`, and the trailing space always lands.
+	 *
+	 * @param draft - the composer draft text in insertion coordinates.
+	 * @param start - the insertion span start offset in that draft.
+	 * @param insertion - the text being inserted.
+	 * @returns the padded insertion text.
+	 */
+	function padInsertion(draft, start, insertion) {
+		const before = start > 0 && !/\s/u.test(draft[start - 1]);
+		const after = !(start < draft.length && /\s/u.test(draft[start]));
+		return `${before ? ' ' : ''}${insertion}${after ? ' ' : ''}`;
+	}
+
+	return {
+		stripTrailingPunctuation,
+		parseLineSuffix,
+		labelOf,
+		matchFileLinesNode,
+		mergeLines,
+		formatMention,
+		relativeMentionPath,
+		fileAddress,
+		padInsertion
+	};
+	
+		})();
+const React = require('react');
+const h = React.createElement;
+
+const NS = 'fileLineReference';
+
+const NUMBERS_STORAGE_KEY = 'flr.numbers';
+const NUMBERS_CLASS = 'flr-numbers';
+
+const zh = {
+	'meta.title': '文件行引用',
+	'meta.description': '选中文件的若干行，把 @路径:起-止 行范围引用插入对话输入框（Ctrl+Shift+L）；点击消息中的引用 chip 回到起始行。当前支持侧栏文件预览。',
+	'action.addLines': '添加选中行到对话',
+	'action.addLinesTitle': '把选中的行以 @路径:起-止 引用插入输入框（Ctrl+Shift+L）',
+	'action.lineMode': '行选择模式',
+	'action.lineModeHint': '行选择模式：点击行选中整行，Shift+点击连选，Ctrl/Cmd+点击增减；再次点击关闭',
+	'action.numbers': '行号',
+	'action.numbersHint': '在纯文本预览中显示行号（代码预览自带行号）',
+	'shortcut.label': '添加选中行到对话'
+};
+
+const en = {
+	'meta.title': 'File Line Reference',
+	'meta.description': 'Select file lines and insert @path:start-end references into the chat composer (Ctrl+Shift+L); click a reference chip in a message to reopen the file at its start line. Currently supports the sidebar file preview.',
+	'action.addLines': 'Add selected lines to chat',
+	'action.addLinesTitle': 'Insert the selected lines as @path:start-end into the composer (Ctrl+Shift+L)',
+	'action.lineMode': 'Line select mode',
+	'action.lineModeHint': 'Line select mode: click selects a line, Shift+click extends, Ctrl/Cmd+click toggles; click again to turn off',
+	'action.numbers': 'Line numbers',
+	'action.numbersHint': 'Show line numbers in the plain-text preview (the code preview has its own)',
+	'shortcut.label': 'Add selected lines to chat'
+};
+
+/** Context services this module reads; activation order comes from package.json `dsh.client.inject`. */
+const inject = ['slots', 'locale', 'sessions', 'uiConversation', 'sidebarRight'];
+
+/* ---------------------------------------------------------------- styles -- */
+
+const STYLE_ID = 'flr-styles';
+const HIGHLIGHT_CLASS = 'flr-line-selected';
+
+const STYLE_TEXT = [
+	`.${HIGHLIGHT_CLASS} { background: color-mix(in srgb, var(--dsw-alias-brand-primary) 18%, transparent); }`,
+	`.flr-chip { display: inline-flex; align-items: center; gap: 4px; padding: 1px 8px; border-radius: 6px; border: none; background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-primary); font-size: 12px; line-height: 18px; max-width: 100%; text-align: left; }`,
+	'button.flr-chip { cursor: pointer; }',
+	'button.flr-chip:hover { background: var(--dsw-alias-bg-layer-1); border-radius: 6px; outline: .5px solid var(--dsw-alias-border-l2); }',
+	'.flr-chip-label { font-weight: 500; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }',
+	'.flr-chip-lines { color: var(--dsw-alias-label-secondary); font-family: var(--dsw-font-mono, ui-monospace, monospace); white-space: nowrap; }',
+	'.flr-chip-icon { flex: none; opacity: .7; }',
+	'.flr-tool-btn { display: inline-flex; align-items: center; justify-content: center; width: 26px; height: 26px; padding: 0; border: none; border-radius: 6px; background: transparent; color: var(--dsw-alias-label-secondary); cursor: pointer; }',
+	'.flr-tool-btn:hover { background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-label-primary); }',
+	'.flr-tool-btn:disabled { opacity: .4; cursor: default; background: transparent; color: var(--dsw-alias-label-secondary); }',
+	'.flr-tool-btn[aria-pressed="true"] { color: var(--dsw-alias-brand-primary); background: color-mix(in srgb, var(--dsw-alias-brand-primary) 12%, transparent); }',
+	`.${NUMBERS_CLASS} [data-textpreview-line]::before { content: attr(data-textpreview-line); display: inline-block; min-width: 3ch; margin-right: 10px; color: var(--dsw-alias-label-secondary); opacity: .75; text-align: right; user-select: none; }`
+].join('\n');
+
+function injectStylesheet() {
+	const existing = document.getElementById(STYLE_ID);
+	if (existing) return () => {};
+	const tag = document.createElement('style');
+	tag.id = STYLE_ID;
+	tag.textContent = STYLE_TEXT;
+	document.head.appendChild(tag);
+	return () => tag.remove();
+}
+
+/* ----------------------------------------------------------------- icons -- */
+
+const ICON_CHAT = h('svg', { width: 16, height: 16, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true },
+	h('path', { d: 'M2.5 3.5A1.5 1.5 0 0 1 4 2h8a1.5 1.5 0 0 1 1.5 1.5v6A1.5 1.5 0 0 1 12 11H6.5L3.8 13.4A.6.6 0 0 1 2.8 13v-2H4a.5.5 0 0 1 .5.5', stroke: 'currentColor', strokeWidth: 1.2, strokeLinecap: 'round', strokeLinejoin: 'round' }),
+	h('path', { d: 'M5 5.5h6M5 8h4', stroke: 'currentColor', strokeWidth: 1.2, strokeLinecap: 'round' })
+);
+
+const ICON_ROWS = h('svg', { width: 16, height: 16, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true },
+	h('rect', { x: 1.5, y: 2.5, width: 13, height: 3.4, rx: 1, fill: 'currentColor', opacity: 0.35 }),
+	h('path', { d: 'M2.6 8.2h10.8M2.6 11.6h10.8', stroke: 'currentColor', strokeWidth: 1.2, strokeLinecap: 'round' }),
+	h('path', { d: 'M13.2 8.2v3.4', stroke: 'currentColor', strokeWidth: 1.6, strokeLinecap: 'round', opacity: 0.55 })
+);
+
+const ICON_FILE = h('svg', { className: 'flr-chip-icon', width: 12, height: 12, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true },
+	h('path', { d: 'M4 1.8h5.2L12.6 5v9.2a.6.6 0 0 1-.6.6H4a.6.6 0 0 1-.6-.6V2.4a.6.6 0 0 1 .6-.6Z', stroke: 'currentColor', strokeWidth: 1.1, strokeLinejoin: 'round' }),
+	h('path', { d: 'M9 2v3.4h3.4', stroke: 'currentColor', strokeWidth: 1.1, strokeLinejoin: 'round' })
+);
+
+const ICON_NUMBERS = h('svg', { width: 16, height: 16, viewBox: '0 0 16 16', fill: 'none', 'aria-hidden': true },
+	h('path', { d: 'M5.6 2 4.4 14M11.6 2 10.4 14M2.4 5.6h11.2M2 10.4h11.2', stroke: 'currentColor', strokeWidth: 1.2, strokeLinecap: 'round' })
+);
+
+/* ----------------------------------------------------- selection controller -- */
+
+/**
+ * Tracks "which preview lines the user has picked" for the document toolbar.
+ *
+ * The preview plugin exposes no selection API, so this module reads its stable
+ * DOM contract: plain-text rows carry `[data-textpreview-line]` (the value is
+ * the 1-based source line), and highlighted code renders `.line` elements in
+ * source order inside the `[data-code-block-content]` scrollport. Every read
+ * goes through `queryTarget()` so a harness update that changes the contract
+ * is a one-function fix.
+ */
+const controller = (() => {
+	const state = {
+		mode: false,
+		selected: [],
+		anchor: null,
+		mouse: null,
+		numbers: true
+	};
+	const listeners = new Set();
+	const decorated = new Set();
+	let lastContainer = null;
+	let attached = 0;
+	let inserter = null;
+
+	function readStoredNumbers() {
+		try {
+			const stored = window.localStorage.getItem(NUMBERS_STORAGE_KEY);
+			return stored === null ? true : stored === '1';
+		} catch {
+			return true;
+		}
+	}
+
+	function applyNumbersClass(on) {
+		document.documentElement.classList.toggle(NUMBERS_CLASS, on);
+	}
+
+	state.numbers = readStoredNumbers();
+	applyNumbersClass(state.numbers);
+
+	function subscribe(listener) {
+		listeners.add(listener);
+		return () => listeners.delete(listener);
+	}
+
+	function notify() {
+		for (const listener of listeners) listener();
+	}
+
+	/**
+	 * Resolve the mounted preview body. Returns `{ kind, container }` where
+	 * `kind` is `'plain' | 'code'`, or null when no line-bearing body exists.
+	 * Prefers a visible container so a floating preview does not shadow the
+	 * active one.
+	 *
+	 * Chat markdown fences also carry `[data-code-block-content]`, so a code
+	 * container is accepted only inside the document preview's own
+	 * `[data-code-preview]` renderer root; chat fences never match and the
+	 * lookup falls through to the plain-text branch.
+	 */
+	function queryTarget() {
+		const isVisible = (el) => el.getClientRects().length > 0;
+		const previews = [...document.querySelectorAll('[data-code-preview]')];
+		const preview = previews.find(isVisible) ?? previews[0];
+		if (preview) {
+			const code = preview.querySelector('[data-code-block-content]');
+			if (code) return { kind: 'code', container: code };
+		}
+		const plains = [...document.querySelectorAll('[data-textpreview-line]')];
+		const first = plains.find((el) => isVisible(el)) ?? plains[0];
+		if (!first) return null;
+		const total = document.querySelectorAll('[data-textpreview-line]').length;
+		// One ancestor must hold every row; with two coexisting plain previews
+		// the walk never resolves and the target stays null (degenerate case).
+		let container = first.parentElement;
+		while (container && container !== document.body && container.querySelectorAll('[data-textpreview-line]').length < total) {
+			container = container.parentElement;
+		}
+		if (!container || container === document.body) return null;
+		return { kind: 'plain', container };
+	}
+
+	/** Discard picks when the preview body changed underneath (tab or file switch). */
+	function ensureFreshTarget() {
+		const target = queryTarget();
+		const identity = target ? target.container : null;
+		if (identity !== lastContainer) {
+			lastContainer = identity;
+			clearHighlight();
+			state.selected = [];
+			state.anchor = null;
+			if (state.mode) {
+				state.mode = false;
+				notify();
+			}
+		}
+		return target;
+	}
+
+	function lineRowOf(element, target) {
+		if (!(element instanceof Element)) return null;
+		if (target.kind === 'plain') {
+			const row = element.closest('[data-textpreview-line]');
+			if (!row || !target.container.contains(row)) return null;
+			return { line: Number(row.getAttribute('data-textpreview-line')), el: row };
+		}
+		const row = element.closest('pre .line');
+		if (!row || !target.container.contains(row)) return null;
+		const rows = target.container.querySelectorAll('pre .line');
+		const index = Array.prototype.indexOf.call(rows, row);
+		return index >= 0 ? { line: index + 1, el: row } : null;
+	}
+
+	function rowForLine(line, target) {
+		if (target.kind === 'plain') {
+			return target.container.querySelector(`[data-textpreview-line="${line}"]`);
+		}
+		return target.container.querySelectorAll('pre .line').item(line - 1);
+	}
+
+	function clearHighlight() {
+		for (const el of decorated) el.classList.remove(HIGHLIGHT_CLASS);
+		decorated.clear();
+	}
+
+	function applyHighlight(target) {
+		clearHighlight();
+		for (const line of state.selected) {
+			const row = rowForLine(line, target);
+			if (row instanceof Element) {
+				row.classList.add(HIGHLIGHT_CLASS);
+				decorated.add(row);
+			}
+		}
+	}
+
+	function onClick(event) {
+		if (!state.mode || event.button !== 0) return;
+		const target = ensureFreshTarget();
+		if (!target) return;
+		const hit = lineRowOf(event.target, target);
+		if (!hit) return;
+		event.preventDefault();
+		event.stopPropagation();
+		if (event.shiftKey && state.anchor !== null) {
+			const [from, to] = state.anchor <= hit.line ? [state.anchor, hit.line] : [hit.line, state.anchor];
+			state.selected = [];
+			for (let n = from; n <= to; n++) state.selected.push(n);
+		} else if (event.ctrlKey || event.metaKey) {
+			state.selected = state.selected.includes(hit.line)
+				? state.selected.filter((n) => n !== hit.line)
+				: [...state.selected, hit.line];
+			state.anchor = hit.line;
+		} else {
+			state.selected = [hit.line];
+			state.anchor = hit.line;
+		}
+		applyHighlight(target);
+		notify();
+	}
+
+	function lineFromNode(node, target) {
+		const element = node instanceof Element ? node : node?.parentElement;
+		if (!element) return null;
+		const hit = lineRowOf(element, target);
+		return hit ? hit.line : null;
+	}
+
+	function onSelectionChange() {
+		const target = ensureFreshTarget();
+		const selection = document.getSelection();
+		if (!target || !selection || selection.rangeCount === 0 || selection.isCollapsed) {
+			if (state.mouse !== null) {
+				state.mouse = null;
+				notify();
+			}
+			return;
+		}
+		const anchor = lineFromNode(selection.anchorNode, target);
+		const focus = lineFromNode(selection.focusNode, target);
+		if (anchor === null && focus === null) {
+			if (state.mouse !== null) {
+				state.mouse = null;
+				notify();
+			}
+			return;
+		}
+		const from = anchor ?? focus;
+		const to = focus ?? anchor;
+		const next = [Math.min(from, to), Math.max(from, to)];
+		if (state.mouse === null || state.mouse[0] !== next[0] || state.mouse[1] !== next[1]) {
+			state.mouse = next;
+			notify();
+		}
+	}
+
+	return {
+		subscribe,
+		/** Refcounted document listeners, alive while a toolbar is mounted. */
+		retain() {
+			attached += 1;
+			if (attached === 1) {
+				document.addEventListener('click', onClick, true);
+				document.addEventListener('selectionchange', onSelectionChange);
+			}
+			return () => {
+				attached -= 1;
+				if (attached === 0) {
+					document.removeEventListener('click', onClick, true);
+					document.removeEventListener('selectionchange', onSelectionChange);
+					state.mode = false;
+					state.selected = [];
+					state.anchor = null;
+					state.mouse = null;
+					clearHighlight();
+				}
+			};
+		},
+		setMode(on) {
+			state.mode = on;
+			state.selected = [];
+			state.anchor = null;
+			state.mouse = null;
+			clearHighlight();
+			notify();
+		},
+		/** Current picked lines: explicit mode picks, else the tracked drag range. */
+		currentLines() {
+			ensureFreshTarget();
+			if (state.mode) return [...state.selected].sort((a, b) => a - b);
+			if (state.mouse === null) return [];
+			const lines = [];
+			for (let n = state.mouse[0]; n <= state.mouse[1]; n++) lines.push(n);
+			return lines;
+		},
+		isMode() {
+			return state.mode;
+		},
+		numbersOn() {
+			return state.numbers;
+		},
+		setNumbers(on) {
+			state.numbers = on;
+			applyNumbersClass(on);
+			try {
+				window.localStorage.setItem(NUMBERS_STORAGE_KEY, on ? '1' : '0');
+			} catch {
+				// Storage unavailable (privacy mode); the toggle stays session-local.
+			}
+			notify();
+		},
+		/** Register the mounted toolbar's insert action for the global hotkey. */
+		setInserter(fn) {
+			inserter = fn;
+			return () => {
+				if (inserter === fn) inserter = null;
+			};
+		},
+		currentInserter() {
+			return inserter;
+		}
+	};
+})();
+
+/* ------------------------------------------------------------ components -- */
+
+/** Session facade captured by apply(); lets action handlers resolve cwd without hooks. */
+let sessionsFacade = null;
+
+/** Workspace root of one session from the facade snapshot; undefined when unknown. */
+function sessionCwd(sessionId) {
+	try {
+		if (sessionId === undefined || sessionId === null || !sessionsFacade) return undefined;
+		return sessionsFacade.list.getSnapshot().byId[sessionId]?.cwd;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Keep one broken render from silently deleting the toolbar: the boundary
+ * logs the failure to the console and drops only the buttons. Falls back to a
+ * pass-through when this React build exposes no Component class, so the
+ * module can never fail to load because of the boundary itself.
+ */
+const ToolbarBoundary = typeof React.Component === 'function'
+	? class ToolbarBoundary extends React.Component {
+		constructor(props) {
+			super(props);
+			this.state = { failed: false };
+		}
+		static getDerivedStateFromError() {
+			return { failed: true };
+		}
+		componentDidCatch(error) {
+			console.error('[file-line-reference] toolbar render failed:', error);
+		}
+		render() {
+			return this.state.failed ? null : this.props.children;
+		}
+	}
+	: function ToolbarBoundary({ children }) {
+		return children;
+	};
+
+/**
+ * Slot component: a single h() call that cannot throw, so the boundary
+ * genuinely encloses ToolbarActions's own render — errors there would
+ * otherwise fly straight to the slot runtime and silently drop the occupant.
+ */
+function ToolbarActionsGuarded(props) {
+	return h(ToolbarBoundary, null, h(ToolbarActions, props));
+}
+
+/**
+ * Toolbar occupant for `sidebar.right.tab.document.actions`.
+ * Owner props: `{ absolutePath }`; session standard props supply `sessionId`
+ * and `inputActions`.
+ *
+ * Hook discipline: this component calls ONLY fixed React hooks — never
+ * hook-valued standard props (`useSession`/`useInput`). Those props can
+ * appear between renders, and a conditional hook call then changes the hook
+ * count mid-life, crashing the slot with React #310 and silently deleting
+ * the toolbar. The workspace root is therefore resolved at action time from
+ * the sessions facade snapshot (the same pattern ui-reference uses).
+ */
+function ToolbarActions(props) {
+	const [, force] = React.useReducer((n) => n + 1, 0);
+	React.useEffect(controller.retain, []);
+	React.useEffect(() => controller.subscribe(force), [force]);
+	React.useEffect(() => {
+		console.info('[file-line-reference] toolbar mounted');
+		return () => console.info('[file-line-reference] toolbar unmounted');
+	}, []);
+
+	const t = props.t;
+	const inputActions = props.inputActions;
+	const absolutePath = props.absolutePath;
+	const latest = React.useRef({ sessionId: props.sessionId, inputActions, absolutePath });
+	latest.current = { sessionId: props.sessionId, inputActions, absolutePath };
+	// Controller reads walk the live preview DOM; keep a DOM surprise from
+	// crashing the render and silently deleting the buttons.
+	let lines = [];
+	let mode = false;
+	let numbers = controller.numbersOn();
+	try {
+		lines = inputActions && absolutePath ? controller.currentLines() : [];
+		mode = controller.isMode();
+	} catch (error) {
+		console.error('[file-line-reference] toolbar state read failed:', error);
+	}
+	const canAdd = lines.length > 0;
+
+	function performInsert() {
+		const { sessionId, inputActions: actions, absolutePath: path } = latest.current;
+		if (!actions || !path) return false;
+		const picked = controller.currentLines();
+		if (picked.length === 0) return false;
+		const cwd = sessionCwd(sessionId);
+		const relative = FlrCore.relativeMentionPath(path, cwd);
+		const mention = FlrCore.formatMention(relative, FlrCore.mergeLines(picked));
+		if (!mention) return false;
+		const span = actions.captureInsertion();
+		// Always pad: a leading space unless the mention opens the draft, and
+		// always a trailing space so text typed next cannot glue to the path.
+		const text = FlrCore.padInsertion('', span.start, mention);
+		if (!actions.insertText(text, span)) {
+			const retry = actions.captureInsertion();
+			if (!actions.insertText(FlrCore.padInsertion('', retry.start, mention), retry)) {
+				console.warn('[file-line-reference] composer rejected the line reference insertion');
+				return false;
+			}
+		}
+		return true;
+	}
+
+	// The global hotkey resolves through the mounted toolbar's inserter.
+	React.useEffect(() => controller.setInserter(() => {
+		try {
+			return performInsert();
+		} catch (error) {
+			console.warn('[file-line-reference] insertion attempt failed:', error);
+			return false;
+		}
+	}), []);
+
+	return [
+		h('button', {
+			key: 'add',
+			className: 'flr-tool-btn',
+			type: 'button',
+			title: t('action.addLinesTitle'),
+			'aria-label': t('action.addLines'),
+			disabled: !canAdd,
+			// pointerdown reads the drag selection before the browser collapses
+			// it on mousedown; click would already see an empty selection.
+			// Keyboard activation (Enter/Space) never fires pointerdown, so the
+			// keydown path below is the keyboard's way in.
+			onPointerDown: (event) => {
+				if (event.button === 0) performInsert();
+			},
+			onKeyDown: (event) => {
+				if (event.key === 'Enter' || event.key === ' ') performInsert();
+			}
+		}, ICON_CHAT),
+		h('button', {
+			key: 'mode',
+			className: 'flr-tool-btn',
+			type: 'button',
+			title: t('action.lineModeHint'),
+			'aria-label': t('action.lineMode'),
+			'aria-pressed': mode,
+			onClick: () => controller.setMode(!mode)
+		}, ICON_ROWS),
+		h('button', {
+			key: 'numbers',
+			className: 'flr-tool-btn',
+			type: 'button',
+			title: t('action.numbersHint'),
+			'aria-label': t('action.numbers'),
+			'aria-pressed': numbers,
+			onClick: () => controller.setNumbers(!numbers)
+		}, ICON_NUMBERS)
+	];
+}
+
+/** `conversation.user.text.node` occupant for the `file-lines` id. */
+function FileLinesChip(props) {
+	const node = props.node;
+	const data = node?.data;
+	if (!data) return null;
+	const lines = data.lineStart === data.lineEnd ? `${data.lineStart}` : `${data.lineStart}-${data.lineEnd}`;
+	const interactive = props.interactive === true && typeof props.openAtLine === 'function';
+	const content = [
+		ICON_FILE,
+		h('span', { key: 'label', className: 'flr-chip-label' }, data.label),
+		h('span', { key: 'lines', className: 'flr-chip-lines' }, `:${lines}`)
+	];
+	if (!interactive) {
+		return h('span', { className: 'flr-chip', title: props.raw }, content);
+	}
+	return h('button', {
+		className: 'flr-chip',
+		type: 'button',
+		title: props.raw,
+		onClick: () => {
+			try {
+				props.openAtLine(data.path, data.lineStart);
+			} catch {
+				// Navigation failures keep the chip; the sidebar surfaces its own dialog.
+			}
+		}
+	}, content);
+}
+
+/* ------------------------------------------------------------------ apply -- */
+
+function apply(ctx) {
+	console.info('[file-line-reference] apply started');
+	ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'flr: dictionaries');
+	const t = ctx.locale.bind(NS);
+	const sessions = ctx.get('sessions');
+	sessionsFacade = sessions;
+
+	ctx.effect(
+		() => ctx.uiConversation.userText.register({
+			id: 'file-lines',
+			order: 20,
+			match(text, from) {
+				// The pipeline treats only `undefined` as "no match"; coerce any
+				// nullish result so `node.start` is never read on a miss.
+				return FlrCore.matchFileLinesNode(text, from) ?? undefined;
+			}
+		}),
+		'flr: file-lines rule'
+	);
+
+	ctx.slots.inject('conversation.user.text.node', function* () {
+		yield ctx.slots.register({
+			name: 'conversation.user.text.node',
+			key: 'file-lines',
+			priority: 100,
+			locale: NS,
+			inject: (sessionId) => ({
+				openAtLine: (path, line) => {
+					const cwd = sessions.list.getSnapshot().byId[sessionId]?.cwd;
+					ctx.sidebarRight.openResource(FlrCore.fileAddress(sessionId, cwd, path), { params: { file: { line } } });
+				}
+			})
+		}, FileLinesChip);
+	});
+
+	ctx.slots.inject('sidebar.right.tab.document.actions', function* () {
+		yield ctx.slots.register(
+			{ name: 'sidebar.right.tab.document.actions', id: 'flr-add-lines', order: 10, locale: NS },
+			ToolbarActionsGuarded
+		);
+	});
+
+	ctx.inject(['shortcuts'], (scope) => {
+		scope.effect(() => {
+			const command = {
+				id: 'fileLineReference.addToChat',
+				label: () => t('shortcut.label'),
+				aliases: ['add selected lines'],
+				defaults: {
+					'desktop:macos': { code: 'KeyL', modifiers: ['primary', 'shift'] },
+					'desktop:windows': { code: 'KeyL', modifiers: ['primary', 'shift'] },
+					'desktop:linux': { code: 'KeyL', modifiers: ['primary', 'shift'] },
+					'web:macos': { code: 'KeyL', modifiers: ['primary', 'shift'] },
+					'web:windows': { code: 'KeyL', modifiers: ['primary', 'shift'] }
+				},
+				regions: ['page', 'editable'],
+				modals: [],
+				resolve: (context) => {
+					// Never act behind an open modal (desktop priority bypasses the
+					// modal check, so this is the only guard).
+					if (context && context.modal) return { status: 'pass' };
+					const perform = controller.currentInserter();
+					if (!perform || controller.currentLines().length === 0) return { status: 'pass' };
+					return { status: 'handled', run: perform };
+				}
+			};
+			// A conflicting default binding throws; fall back to an unbound
+			// command the user can assign in the shortcut settings.
+			try {
+				scope.shortcuts.register(command);
+			} catch (error) {
+				console.warn('[file-line-reference] shortcut defaults rejected, retrying unbound:', error);
+				try {
+					scope.shortcuts.register({ ...command, defaults: {} });
+				} catch (fallbackError) {
+					console.warn('[file-line-reference] shortcut registration failed:', fallbackError);
+				}
+			}
+		}, 'flr: shortcut');
+	});
+
+	ctx.effect(() => {
+		const removeStyles = injectStylesheet();
+		return () => {
+			removeStyles();
+			document.documentElement.classList.remove(NUMBERS_CLASS);
+		};
+	}, 'flr: styles');
+	console.info('[file-line-reference] apply finished');
+}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		return module.exports;
+	}
+});

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: file-line-reference
+      name: '@dybai/file-line-reference'

package/icon.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect x="10" y="6" width="32" height="42" rx="4" fill="#247bbf" opacity="0.14"/>
+  <rect x="10" y="6" width="32" height="42" rx="4" fill="none" stroke="#247bbf" stroke-width="3"/>
+  <line x1="17" y1="17" x2="35" y2="17" stroke="#247bbf" stroke-width="3" stroke-linecap="round"/>
+  <line x1="17" y1="25" x2="31" y2="25" stroke="#247bbf" stroke-width="3" stroke-linecap="round"/>
+  <rect x="15" y="31" width="22" height="9" rx="2.5" fill="#247bbf" opacity="0.45"/>
+  <path d="M32 42h16a7 7 0 0 1 7 7v6a7 7 0 0 1-7 7h-5l-7 5v-5h-4a7 7 0 0 1-7-7v-6a7 7 0 0 1 7-7z" fill="#247bbf"/>
+  <circle cx="40" cy="52" r="2" fill="#ffffff"/>
+  <circle cx="47" cy="52" r="2" fill="#ffffff"/>
+  <circle cx="54" cy="52" r="2" fill="#ffffff"/>
+</svg>

package/index.js

@@ -0,0 +1,2 @@
+/** Host half of the bundle; the Client module owns all behavior. */
+export function apply() {}

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "File Line Reference",
+    "description": "Select file lines and insert @path:start-end references into the chat composer; click a reference chip in a message to reopen the file at its start line. Currently supports the sidebar file preview."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "文件行引用",
+    "description": "选中文件的若干行，把 @路径:起-止 行范围引用插入对话输入框；点击消息中的引用 chip 回到起始行。当前支持侧栏文件预览。"
+  }
+}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@dybai/file-line-reference",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Select file lines and add @path:start-end line-range references to the chat composer; click a reference chip to reopen the file at its start line",
+  "scripts": {
+    "test": "node --test",
+    "build": "node scripts/build.mjs"
+  },
+  "engines": {
+    "dsh": ">=0.2.1-rc.5"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg"
+  },
+  "files": ["index.js", "client.js", "cordis.patch.yml", "locale/*.json", "icon.svg"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dybai/file-line-reference.git"
+  },
+  "keywords": ["dsh", "deepseek-harness", "line-reference", "file-preview"],
+  "license": "MIT",
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-sidebar-documentpreview"
+      ]
+    }
+  }
+}