@lincyaw/language-server 0.0.0-stage → 1.0.0-rc.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @lincyaw/language-server
 
-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.
+Language server for canonical `lecture.json` teaching documents: shared validation, normalized entity definitions, project code anchor definitions and hovers, and preview synchronization by stable page ownership.
+
+Part of [Presmium](https://github.com/Lincyaw/presmium), which derives web pages, slides, Jupyter notebooks and narrated playback from the same teaching document.
+
+## Usage
+
+```sh
+pnpm exec presmium-language-server --stdio
+```
+
+It also takes `--node-ipc` and `--socket=<port>`. Clients select `**/lecture.json` using their native JSON editor and associate the public kernel schema for completion. The VS Code extension generates and bundles this schema from `DOCUMENT_JSON_SCHEMA`; the server adds syntax and domain graph diagnostics using `validateDocument`.
+
+Opened buffers are validated without writing or compiling unsaved text. Saving JSON and notifications for watched project inputs trigger a real compiler run. Diagnostics resolve JSON pointers to token ranges; entity and `origin.anchor` definitions navigate to their authoritative JSON or project code. `presmium/section` locates a page from the entity under the cursor, including normalized blocks, steps and narration. `presmium/preview` starts a real `presmium dev` web server for the canonical entry and stops it when the language server closes.
+
+Compilation and preview prefer the document's installed `@lincyaw/presmium` package, which supplies its bundled plugins and renderers. A standalone installation uses the project's CLI or the language server's own CLI dependencies.
+
+The server does not register its own completion provider: JSON schema completion remains with the editor. The studio provides native rich-text editing of the same `lecture.json` document.
+
+## Documentation
+
+- [Author guide](https://github.com/Lincyaw/presmium/blob/main/site/guide/locales/en/lecture.json)
+
+## License
+
+Apache-2.0

package/bin/presmium-language-server.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { createJiti } from 'jiti'
+
+console.log = console.info = console.debug = console.error
+
+const emitWarning = process.emitWarning
+process.emitWarning = (warning, ...args) => {
+  const code = typeof args[0] === 'object' ? args[0]?.code : args[1]
+  if (code !== 'DEP0040') emitWarning.call(process, warning, ...args)
+}
+
+const jiti = createJiti(import.meta.url)
+const { startServer } = await jiti.import('../src/node/server.ts')
+startServer()

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@lincyaw/language-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "description": "Language server for canonical lecture.json documents: validation, entity navigation, code anchors and preview sync",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lincyaw/presmium.git",
+    "directory": "packages/language-server"
+  },
+  "homepage": "https://github.com/Lincyaw/presmium/tree/main/packages/language-server#readme",
+  "bugs": "https://github.com/Lincyaw/presmium/issues",
+  "keywords": [
+    "presmium",
+    "lsp",
+    "language-server"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "presmium-language-server": "./bin/presmium-language-server.mjs"
+  },
+  "exports": {
+    "./domain": "./src/domain/index.ts",
+    "./protocol": "./src/domain/protocol.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "dependencies": {
+    "jiti": "^2.7.0",
+    "jsonc-parser": "3.3.1",
+    "vscode-languageserver": "10.1.2",
+    "vscode-languageserver-textdocument": "1.0.15",
+    "@lincyaw/cli": "1.0.0-rc.1",
+    "@lincyaw/compiler": "1.0.0-rc.1",
+    "@lincyaw/kernel": "1.0.0-rc.1",
+    "@lincyaw/viewer": "1.0.0-rc.1",
+    "@lincyaw/host": "1.0.0-rc.1",
+    "@lincyaw/web": "1.0.0-rc.1"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/domain/document.ts

@@ -0,0 +1,92 @@
+import { isRecord, validateDocument } from '@lincyaw/kernel'
+import type { TeachingDocument } from '@lincyaw/kernel'
+import { findNodeAtLocation, findNodeAtOffset, getNodePath, getNodeValue, parseTree } from 'jsonc-parser'
+import type { JSONPath, Node, ParseError } from 'jsonc-parser'
+
+/** Strict JSON syntax, using parser offsets unchanged even when the entry has a BOM. */
+export function readDocument(text: string) {
+  const errors: ParseError[] = []
+  const tree = parseTree(text.replace(/^\uFEFF/, ' '), errors, { disallowComments: true, allowTrailingComma: false, allowEmptyContent: false })
+  const validation = tree && !errors.length ? validateDocument(getNodeValue(tree)) : undefined
+  return { tree, errors, validation, document: validation?.document }
+}
+
+export function nodeAt(tree: Node, offset: number): { node: Node, path: JSONPath } | undefined {
+  const node = findNodeAtOffset(tree, offset, true)
+  return node ? { node, path: getNodePath(node) } : undefined
+}
+
+/** Missing properties point at the closest existing parent, rather than an invented source line. */
+export function nodeAtPointer(tree: Node, pointer: string): Node {
+  const path = pointer.replace(/^#/, '').split('/').slice(1).map(key => key.replaceAll('~1', '/').replaceAll('~0', '~'))
+  let node = tree
+  for (const key of path) {
+    const found = findNodeAtLocation(node, [node.type === 'array' ? Number(key) : key])
+    if (!found) break
+    node = found
+  }
+  return node
+}
+
+function owners(document: TeachingDocument): Map<string, string> {
+  const result = new Map<string, string>()
+  const rich = (node: unknown, section: string) => {
+    if (!isRecord(node)) return
+    if (typeof node.id === 'string') result.set(node.id, section)
+    if (Array.isArray(node.children)) node.children.forEach(child => rich(child, section))
+    if (Array.isArray(node.fallback)) node.fallback.forEach(child => rich(child, section))
+  }
+  const visit = (id: string, section: string) => {
+    result.set(id, section)
+    const block = document.blocks[id]!
+    if (block.type === 'container' || block.type === 'component') block.children?.forEach(child => visit(child, section))
+    if (block.type === 'text') block.content.forEach(node => rich(node, section))
+  }
+  for (const id of document.sectionOrder) {
+    result.set(`page:${id}`, id)
+    document.sections[id]!.children.forEach(child => visit(child, id))
+  }
+  return result
+}
+
+/** Entity ownership determines the page even if normalized maps are reordered or minified. */
+export function sectionAtPath(document: TeachingDocument, path: JSONPath): string | undefined {
+  const [map, id, field, key] = path
+  const owner = owners(document)
+  const narration = (id: string) => document.sectionOrder.find(section => document.sections[section]!.stepOrder.some(step => document.steps[step]!.narrationIds.includes(id)))
+  const usedBlock = (predicate: (block: TeachingDocument['blocks'][string]) => boolean) => Object.values(document.blocks).find(predicate)?.id
+  if (map === 'sections' && typeof id === 'string') return document.sections[id]?.id
+  if (map === 'sectionOrder' && typeof id === 'number') return document.sectionOrder[id]
+  if (map === 'blocks' && typeof id === 'string') return owner.get(id)
+  if (map === 'steps' && typeof id === 'string') return document.steps[id]?.sectionId
+  if (map === 'narrations' && typeof id === 'string') return narration(id)
+  if (map === 'definitions' && typeof id === 'string') return owner.get(usedBlock(block => block.type === 'component' && block.definitionId === id) ?? '')
+  if (map === 'assets' && typeof id === 'string') return owner.get(usedBlock(block => block.type === 'image' && block.assetId === id) ?? '')
+  if (map === 'production') {
+    if (id === 'sectionOverrides' && typeof field === 'string') return document.sections[field]?.id
+    if (id === 'stepOverrides' && typeof field === 'string') return document.steps[field]?.sectionId
+    if (id === 'narrationOverrides' && typeof field === 'string') return narration(field)
+    if (id === 'cueTimings' && typeof field === 'string') {
+      const owner = Object.values(document.narrations).find(value => value.content.some(node => node.type === 'cue' && node.id === field))
+      return owner && narration(owner.id)
+    }
+    if (id === 'mediaClips' && typeof field === 'number') return document.steps[document.production.mediaClips[field]?.attachment.stepId ?? '']?.sectionId
+  }
+  if (map === 'comments' && typeof id === 'string') return owner.get(document.comments?.[id]?.anchor?.[key === 'to' ? 'to' : 'from'].blockId ?? '')
+  return map === 'metadata' || !path.length ? document.sectionOrder[0] : undefined
+}
+
+export function entityReference(document: TeachingDocument, path: JSONPath, value: unknown): JSONPath | undefined {
+  if (typeof value !== 'string') return undefined
+  const [root, , field] = path, last = path.at(-1)
+  const child = path.length === 4 && field === 'children' && (root === 'sections' || root === 'blocks')
+  const visual = root === 'steps' && field === 'visuals' && path.length === 5 && last === 'blockId'
+  const cue = root === 'narrations' && field === 'content' && path.length === 6 && path.at(-2) === 'target' && last === 'blockId'
+  const asset = last === 'assetId' && (root === 'blocks' && path.length === 3 || root === 'production' && (path.at(-2) === 'voiceSource' || path[1] === 'mediaClips' && path.length === 4))
+  const map = root === 'sectionOrder' && path.length === 2 || root === 'steps' && field === 'sectionId' && path.length === 3 ? 'sections'
+    : root === 'blocks' && field === 'definitionId' && path.length === 3 ? 'definitions'
+    : asset ? 'assets' : child || visual || cue ? 'blocks'
+    : root === 'sections' && field === 'stepOrder' && path.length === 4 || root === 'steps' && field === 'inherits' && path.length === 3 || root === 'production' && path[1] === 'mediaClips' && path.at(-2) === 'attachment' && last === 'stepId' ? 'steps'
+    : root === 'steps' && field === 'narrationIds' && path.length === 4 ? 'narrations' : undefined
+  return map && Object.hasOwn(document[map], value) ? [map, value] : undefined
+}

package/src/domain/index.ts

@@ -0,0 +1,6 @@
+export { entityReference, nodeAt, nodeAtPointer, readDocument, sectionAtPath } from './document.ts'
+export { LS_MESSAGES } from './messages.ts'
+export type { LsMessages } from './messages.ts'
+export { previewUrl } from './preview-url.ts'
+export { PREVIEW_REQUEST, SECTION_REQUEST } from './protocol.ts'
+export type { DocumentParams, PositionParams, Preview, SectionLocation } from './protocol.ts'

package/src/domain/messages.ts

@@ -0,0 +1,30 @@
+import type { Locale } from '@lincyaw/kernel'
+
+export const LS_MESSAGES = {
+  'zh-CN': {
+    status: { exact: '已解析', moved: '已移动', fuzzy: '待确认', lost: '已失效' } as Record<string, string>,
+    pinnedAt: (commit: string) => `锁定在 ${commit}`,
+    drifted: '锁定之后已漂移',
+    recordedOutput: '录制的输出',
+    timedOut: '超时',
+    exitCode: (code: number | null) => `退出码 ${code}`,
+    noOutput: '（没有输出）',
+    runsLive: '*配置为在浏览器中执行，尚无录制输出。*',
+    notRecorded: '*还没有录制的输出。*',
+    moreLines: (count: number) => `…… 另有 ${count} 行`,
+  },
+  'en': {
+    status: { exact: 'exact', moved: 'moved', fuzzy: 'to confirm', lost: 'lost' } as Record<string, string>,
+    pinnedAt: (commit: string) => `pinned at ${commit}`,
+    drifted: 'drifted since the pin',
+    recordedOutput: 'Recorded output',
+    timedOut: 'timed out',
+    exitCode: (code: number | null) => `exit code ${code}`,
+    noOutput: '(no output)',
+    runsLive: '*Configured to run in the browser; no recorded output.*',
+    notRecorded: '*No recorded output yet.*',
+    moreLines: (count: number) => `… ${count} more lines`,
+  },
+} satisfies Record<Locale, unknown>
+
+export type LsMessages = (typeof LS_MESSAGES)[Locale]

package/src/domain/preview-url.ts

@@ -0,0 +1,11 @@
+import type { SectionLocation } from './protocol.ts'
+
+const page = (link: string) => link.split('#')[0]!
+
+export function previewUrl(base: string, section: SectionLocation | null | undefined, shown?: SectionLocation): string {
+  const root = base.replace(/\/?$/, '/')
+  if (!section) return root
+  const id = encodeURIComponent(section.id)
+  const target = shown && page(shown.link) === page(section.link) ? `${page(section.link)}#${id}` : `${page(section.link)}?section=${id}`
+  return new URL(target.replace(/^\//, ''), root).href
+}

package/src/domain/protocol.ts

@@ -0,0 +1,25 @@
+export interface DocumentParams {
+  textDocument: { uri: string }
+}
+
+export interface PositionParams extends DocumentParams {
+  position: { line: number, character: number }
+}
+
+export const PREVIEW_REQUEST = 'presmium/preview'
+
+export interface Preview {
+  entry: string
+  url: string
+}
+
+export const SECTION_REQUEST = 'presmium/section'
+
+/** The section at a position in a source file, and its page in the web form. */
+export interface SectionLocation {
+  entry: string
+  id: string
+  index: number
+  title: string
+  link: string
+}

package/src/node/anchors.ts

@@ -0,0 +1,60 @@
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Compilation } from '@lincyaw/compiler'
+import { docBlocks, isRenderable } from '@lincyaw/kernel'
+import type { AnchorString, CodeNode, Resolution, ResolvedLocation } from '@lincyaw/kernel'
+import { MarkupKind } from 'vscode-languageserver/node'
+import type { Hover, Location, Range } from 'vscode-languageserver/node'
+import type { LsMessages } from '../domain/index.ts'
+
+const MAX_LINES = 60
+export interface AnchorRef { anchor: AnchorString, blockId: string, pin?: string, range: Range }
+
+function resolveAnchor(compilation: Compilation, ref: AnchorRef): Promise<Resolution> {
+  return compilation.resolvers.resolve(ref.anchor, compilation.src, compilation.lock.get(ref.anchor), ref.pin)
+}
+function locationOf(compilation: Compilation, location: ResolvedLocation): Location {
+  const last = location.text.split(/\r?\n/).at(-1) ?? ''
+  return { uri: pathToFileURL(resolve(compilation.workspaceRoot, location.file)).href,
+    range: { start: { line: location.startLine - 1, character: 0 }, end: { line: location.endLine - 1, character: last.length } } }
+}
+export async function anchorDefinition(compilation: Compilation, ref: AnchorRef): Promise<Location[]> {
+  const resolution = await resolveAnchor(compilation, ref)
+  return (resolution.location ? [resolution.location] : resolution.candidates ?? []).map(location => locationOf(compilation, location))
+}
+function fenced(t: LsMessages, text: string, lang = ''): string {
+  const lines = text.replace(/\n+$/, '').split('\n')
+  const shown = lines.length > MAX_LINES ? [...lines.slice(0, MAX_LINES), t.moreLines(lines.length - MAX_LINES)] : lines
+  const fence = '`'.repeat(Math.max(3, ...[...text.matchAll(/`+/g)].map(m => m[0].length + 1)))
+  return `${fence}${lang}\n${shown.join('\n')}\n${fence}`
+}
+function where(file: string, startLine: number, endLine: number): string { return `\`${file}:${startLine}-${endLine}\`` }
+export async function anchorHover(compilation: Compilation, ref: AnchorRef, t: LsMessages): Promise<Hover> {
+  const block = [...docBlocks(compilation.doc)].find(({ block }) => block.id === ref.blockId)?.block
+  const node = block?.node.type === 'code' && block.node.origin?.anchor === ref.anchor && block.node.origin?.pin === ref.pin ? block.node : undefined
+  const parts = node?.origin && node.origin.startLine > 0 ? codeNodeHover(node, t) : await resolvedHover(compilation, ref, t)
+  return { contents: { kind: MarkupKind.Markdown, value: parts.join('\n\n') }, range: ref.range }
+}
+
+function codeNodeHover(node: CodeNode, t: LsMessages): string[] {
+  const origin = node.origin!
+  const notes = [t.status[origin.status] ?? origin.status, origin.pin && t.pinnedAt(origin.pin.slice(0, 7)), origin.drift === 'drifted' && t.drifted].filter(Boolean)
+  const parts = [`**${origin.anchor}** ${where(origin.file, origin.startLine, origin.endLine)} (${notes.join(', ')})`, fenced(t, node.value, node.lang)]
+  const run = node.outputs?.[0]
+  if (run) {
+    const status = run.timedOut ? t.timedOut : run.ok ? `${run.durationMs} ms` : t.exitCode(run.exitCode)
+    parts.push(`**${t.recordedOutput}** (${run.executorId}, ${status})`, fenced(t, [run.stdout, run.stderr].filter(Boolean).join('\n') || t.noOutput))
+  } else if (node.run) {
+    parts.push(node.run.when === 'live' ? t.runsLive : t.notRecorded)
+  }
+  return parts
+}
+
+async function resolvedHover(compilation: Compilation, ref: AnchorRef, t: LsMessages): Promise<string[]> {
+  const resolution = await resolveAnchor(compilation, ref)
+  const { location } = resolution
+  const parts = [[`**${ref.anchor}**`, location && where(location.file, location.startLine, location.endLine), `(${t.status[resolution.status] ?? resolution.status})`].filter(Boolean).join(' ')]
+  if (resolution.message) parts.push(resolution.message)
+  if (location && isRenderable(resolution)) parts.push(fenced(t, location.text, /\.([\w-]+)$/.exec(location.file)?.[1] ?? ''))
+  return parts
+}

package/src/node/decks.ts

@@ -0,0 +1,103 @@
+import { basename, join } from 'node:path'
+import { readFileSync } from 'node:fs'
+import { Compiler, DECK_ENTRY } from '@lincyaw/compiler'
+import type { Compilation } from '@lincyaw/compiler'
+import { ANCHOR_LOCK_PATH, errorMessage, fnv1a64 } from '@lincyaw/kernel'
+import type { Finding } from '@lincyaw/kernel'
+import { documentCli } from './document-cli.ts'
+
+export class Deck {
+  readonly entry: string
+  readonly #compiler: Compiler
+  readonly #compiled: (deck: Deck) => void
+  compilation?: Compilation
+  findings: Finding[] = []
+  sourceFingerprint?: string
+  #running?: Promise<void>
+  #again = false
+  #version = 0
+  #completedVersion = -1
+
+  constructor(entry: string, compiled: (deck: Deck) => void) {
+    this.entry = entry
+    this.#compiler = new Compiler(entry, { bundled: documentCli(entry).bundled })
+    this.#compiled = compiled
+  }
+
+  compile(): Promise<void> {
+    if (this.#running) {
+      this.#again = true
+      return this.#running
+    }
+    this.#running = (async () => {
+      do {
+        this.#again = false
+        await this.#compileOnce()
+      } while (this.#again)
+      this.#running = undefined
+    })()
+    return this.#running
+  }
+
+  ready(): Promise<void> {
+    return this.#running ?? Promise.resolve()
+  }
+
+  invalidate(): void { this.#version++ }
+  get findingsCurrent(): boolean { return this.#completedVersion === this.#version }
+
+  dependsOn(file: string): boolean {
+    const { compilation } = this
+    if (!compilation) return file === this.entry
+    return compilation.sourceFiles.includes(file) || compilation.inputs.files.includes(file) || file === join(compilation.deckDir, ANCHOR_LOCK_PATH)
+  }
+
+  async #compileOnce(): Promise<void> {
+    const version = this.#version
+    let attemptedFingerprint: string | undefined
+    try { attemptedFingerprint = fnv1a64(readFileSync(this.entry, 'utf8')) } catch { /* The compiler reports unavailable entries. */ }
+    try {
+      const compilation = await this.#compiler.compile()
+      this.findings = [...compilation.doc.diagnostics, ...await compilation.check()]
+      this.compilation = compilation
+      this.sourceFingerprint = compilation.sourceFingerprints?.[this.entry]
+    } catch (error) {
+      this.compilation = undefined
+      this.sourceFingerprint = attemptedFingerprint
+      this.findings = [{ checkId: 'presmium.compile', severity: 'error', message: errorMessage(error), source: { file: this.entry, line: 1 } }]
+    }
+    this.#completedVersion = version
+    if (this.findingsCurrent && !this.#again) this.#compiled(this)
+  }
+}
+
+export class Decks {
+  readonly #decks = new Map<string, Deck>()
+  readonly #compiled: (deck: Deck) => void
+
+  constructor(compiled: (deck: Deck) => void) {
+    this.#compiled = compiled
+  }
+
+  all(): Deck[] {
+    return [...this.#decks.values()]
+  }
+
+  open(entry: string): Deck {
+    let deck = this.#decks.get(entry)
+    if (!deck) {
+      deck = new Deck(entry, this.#compiled)
+      this.#decks.set(entry, deck)
+      void deck.compile()
+    }
+    return deck
+  }
+
+  /** Only the canonical JSON entry opens a document; project inputs are watched dependencies. */
+  async findByFile(file: string): Promise<Deck | undefined> {
+    if (basename(file) !== DECK_ENTRY) return undefined
+    const deck = this.open(file)
+    await deck.ready()
+    return deck
+  }
+}

package/src/node/dev-server-launcher.ts

@@ -0,0 +1,89 @@
+import { spawn } from 'node:child_process'
+import type { ChildProcess } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { documentCli } from './document-cli.ts'
+
+const START_TIMEOUT = 120_000
+const PREVIEW_DIR = '.presmium/preview'
+
+function stopProcess(child: ChildProcess, signal: NodeJS.Signals = 'SIGTERM'): void {
+  if (!child.pid || child.exitCode !== null || child.signalCode !== null) return
+  if (process.platform === 'win32') {
+    const task = spawn('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true, stdio: 'ignore' })
+    task.once('error', () => { child.kill(signal) })
+  } else child.kill(signal)
+}
+
+/** Starts a `presmium dev` web server for each deck the editor previews, once, and stops them all on close. */
+export class DevServerLauncher {
+  readonly #urls = new Map<string, Promise<string>>()
+  readonly #children = new Set<ChildProcess>()
+  readonly #log: (line: string) => void
+
+  constructor(log: (line: string) => void) {
+    this.#log = log
+  }
+
+  /** The address of the deck's dev server, started on first use. */
+  urlOf(entry: string): Promise<string> {
+    const known = this.#urls.get(entry)
+    if (known) return known
+    const forget = () => {
+      if (this.#urls.get(entry) === url) this.#urls.delete(entry)
+    }
+    const url: Promise<string> = this.#start(entry, forget)
+    this.#urls.set(entry, url)
+    url.catch(forget)
+    return url
+  }
+
+  #start(entry: string, forget: () => void): Promise<string> {
+    const deckDir = dirname(entry)
+    const args = [documentCli(entry).bin, 'dev', entry, '--to', 'web', '--out', join(deckDir, PREVIEW_DIR)]
+    // The lines read below are the English ones: `presmium dev` prints in the system's language.
+    const child = spawn(process.execPath, args, { cwd: deckDir, stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, LC_ALL: 'en_US.UTF-8' } })
+    this.#children.add(child)
+    return new Promise((resolve, reject) => {
+      let started = false
+      const fail = (error: Error) => {
+        clearTimeout(timer)
+        reject(error)
+        if (!started) stopProcess(child)
+      }
+      const timer = setTimeout(() => fail(new Error('presmium dev did not start the web server in time')), START_TIMEOUT)
+      createInterface({ input: child.stderr! }).on('line', line => this.#log(line))
+      createInterface({ input: child.stdout! }).on('line', (line) => {
+        this.#log(line)
+        if (started) return
+        const url = /^web\s+(https?:\/\/\S+)/.exec(line)?.[1]
+        if (url) {
+          started = true
+          clearTimeout(timer)
+          resolve(url)
+        } else if (line.startsWith('watching;')) {
+          fail(new Error('presmium dev started no web server; is the web renderer installed?'))
+        }
+      })
+      child.once('error', fail)
+      child.once('exit', (code) => {
+        this.#children.delete(child)
+        forget()
+        fail(new Error(`presmium dev exited with code ${code}`))
+      })
+    })
+  }
+
+  async close(): Promise<void> {
+    const exits = [...this.#children].map(child => new Promise<void>((done) => {
+      const timer = setTimeout(() => {
+        stopProcess(child, 'SIGKILL')
+        done()
+      }, 5000).unref()
+      child.once('exit', () => { clearTimeout(timer); done() })
+      stopProcess(child)
+    }))
+    this.#urls.clear()
+    await Promise.all(exits)
+  }
+}

package/src/node/diagnostics.ts

@@ -0,0 +1,40 @@
+import type { Finding, Severity, SourcePos } from '@lincyaw/kernel'
+import { printParseErrorCode } from 'jsonc-parser'
+import { TextDocument } from 'vscode-languageserver-textdocument'
+import { DiagnosticSeverity } from 'vscode-languageserver/node'
+import type { Diagnostic, Range } from 'vscode-languageserver/node'
+import { nodeAtPointer, readDocument } from '../domain/document.ts'
+
+const SEVERITY: Record<Severity, DiagnosticSeverity> = { error: DiagnosticSeverity.Error, warning: DiagnosticSeverity.Warning, info: DiagnosticSeverity.Information }
+export const offsetRange = (document: TextDocument, offset: number, length: number): Range => ({ start: document.positionAt(offset), end: document.positionAt(offset + Math.max(1, length)) })
+
+/** The same syntax and graph validator used by source saves, before compilation is available. */
+export function documentDiagnostics(text: string): Diagnostic[] {
+  const document = TextDocument.create('', 'json', 0, text), source = readDocument(text)
+  return [
+    ...source.errors.map(error => ({ range: offsetRange(document, error.offset, error.length), severity: DiagnosticSeverity.Error, source: 'presmium', code: 'document.json', message: printParseErrorCode(error.error) })),
+    ...(source.validation?.issues.map(issue => {
+      const node = nodeAtPointer(source.tree!, issue.path)
+      return { range: offsetRange(document, node.offset, node.length), severity: SEVERITY[issue.severity], source: 'presmium', code: issue.code, message: issue.message }
+    }) ?? []),
+  ]
+}
+
+/** Compiler JSON pointers resolve to real token ranges; project findings retain their code lines. */
+export function diagnosticsByFile(findings: Finding[], entry: string, textOf: (file: string) => string): Map<string, Diagnostic[]> {
+  const byFile = new Map<string, Diagnostic[]>(), documents = new Map<string, TextDocument>()
+  const trees = new Map<string, ReturnType<typeof readDocument>['tree']>()
+  for (const finding of findings) {
+    const source = finding.source as SourcePos | undefined, file = source?.file ?? entry
+    let document = documents.get(file)
+    if (!document) { document = TextDocument.create('', 'json', 0, textOf(file)); documents.set(file, document) }
+    if (source?.pointer && !trees.has(file)) trees.set(file, readDocument(document.getText()).tree)
+    const tree = trees.get(file)
+    const node = tree && source?.pointer ? nodeAtPointer(tree, source.pointer) : undefined
+    const line = Math.max(1, source?.line ?? 1) - 1, text = document.getText().split(/\r?\n/)[line] ?? ''
+    const range = node ? offsetRange(document, node.offset, node.length) : { start: { line, character: text.length - text.trimStart().length }, end: { line, character: text.trimEnd().length } }
+    const diagnostic: Diagnostic = { range, severity: SEVERITY[finding.severity], source: 'presmium', code: finding.checkId, message: finding.hint ? `${finding.message}\n${finding.hint}` : finding.message }
+    byFile.set(file, [...byFile.get(file) ?? [], diagnostic])
+  }
+  return byFile
+}

package/src/node/document-cli.ts

@@ -0,0 +1,19 @@
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { findPackageDir } from '@lincyaw/compiler'
+import { findPackageBin } from '@lincyaw/kernel/node'
+
+/** The document's installed command and the package that supplies its bundled plugins. */
+export function documentCli(entry: string): { bin: string, bundled: string } {
+  const project = dirname(entry)
+  for (const [name, from] of [
+    ['@lincyaw/presmium', project],
+    ['@lincyaw/cli', project],
+    ['@lincyaw/cli', dirname(fileURLToPath(import.meta.url))],
+  ] as const) {
+    const bundled = findPackageDir(name, from)
+    const bin = findPackageBin(name, 'presmium', join(from, 'package.json'))
+    if (bundled && bin) return { bin, bundled }
+  }
+  throw new Error('@lincyaw/cli is not installed')
+}

package/src/node/server.ts

@@ -0,0 +1,126 @@
+import { readFileSync } from 'node:fs'
+import { basename } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { DOCUMENT_ENTRY, fnv1a64 } from '@lincyaw/kernel'
+import type { AnchorString } from '@lincyaw/kernel'
+import { sectionLinks, webPages } from '@lincyaw/web/domain'
+import { findNodeAtLocation, getNodeValue } from 'jsonc-parser'
+import { TextDocument } from 'vscode-languageserver-textdocument'
+import { createConnection, DidChangeWatchedFilesNotification, ProposedFeatures, TextDocuments, TextDocumentSyncKind } from 'vscode-languageserver/node'
+import { entityReference, LS_MESSAGES, nodeAt, readDocument, sectionAtPath, PREVIEW_REQUEST, SECTION_REQUEST } from '../domain/index.ts'
+import type { DocumentParams, PositionParams, Preview, SectionLocation } from '../domain/index.ts'
+import { anchorDefinition, anchorHover } from './anchors.ts'
+import type { AnchorRef } from './anchors.ts'
+import { Decks } from './decks.ts'
+import type { Deck } from './decks.ts'
+import { DevServerLauncher } from './dev-server-launcher.ts'
+import { diagnosticsByFile, documentDiagnostics, offsetRange } from './diagnostics.ts'
+
+const COMPILE_DELAY = 50
+const fileOf = (uri: string): string | undefined => uri.startsWith('file:') ? fileURLToPath(uri) : undefined
+const canonical = (file: string | undefined): file is string => !!file && basename(file) === DOCUMENT_ENTRY
+function fileText(file: string): string { try { return readFileSync(file, 'utf8') } catch { return '' } }
+
+export function startServer(): void {
+  const connection = createConnection(ProposedFeatures.all), documents = new TextDocuments(TextDocument)
+  const devServers = new DevServerLauncher(line => connection.console.log(line))
+  const published = new Map<Deck, Set<string>>(), timers = new Map<Deck, NodeJS.Timeout>()
+  const textOf = (file: string) => documents.get(pathToFileURL(file).href)?.getText() ?? fileText(file)
+  const publishDiagnostics = (deck: Deck) => {
+    const text = textOf(deck.entry), disk = fileText(deck.entry), source = documentDiagnostics(text)
+    const findings = !deck.findingsCurrent || deck.sourceFingerprint !== fnv1a64(disk) || source.some(d => d.severity === 1) || text.replace(/^\uFEFF/, '') !== disk.replace(/^\uFEFF/, '') ? [] : deck.findings
+    const byFile = diagnosticsByFile(findings, deck.entry, textOf)
+    byFile.set(deck.entry, [...source, ...byFile.get(deck.entry) ?? []])
+    const files = new Set([...deck.compilation?.sourceFiles ?? [deck.entry], ...byFile.keys()])
+    const uris = new Set([...files].map(file => pathToFileURL(file).href))
+    for (const file of files) {
+      const uri = pathToFileURL(file).href
+      void connection.sendDiagnostics({ uri, version: documents.get(uri)?.version, diagnostics: byFile.get(file) ?? [] })
+    }
+    for (const uri of published.get(deck) ?? []) if (!uris.has(uri)) void connection.sendDiagnostics({ uri, diagnostics: [] })
+    published.set(deck, uris)
+  }
+  const decks = new Decks(publishDiagnostics)
+  const changed = (files: string[]) => {
+    for (const deck of decks.all().filter(d => files.some(file => d.dependsOn(file)))) {
+      deck.invalidate()
+      clearTimeout(timers.get(deck))
+      timers.set(deck, setTimeout(() => { timers.delete(deck); void deck.compile() }, COMPILE_DELAY))
+    }
+  }
+
+  let watchFiles = false
+  connection.onInitialize(({ capabilities }) => {
+    watchFiles = capabilities.workspace?.didChangeWatchedFiles?.dynamicRegistration === true
+    return { capabilities: {
+      textDocumentSync: { openClose: true, change: TextDocumentSyncKind.Incremental, save: { includeText: false } },
+      definitionProvider: true, hoverProvider: true,
+    }, serverInfo: { name: 'presmium-language-server' } }
+  })
+  connection.onInitialized(() => {
+    if (watchFiles) void connection.client.register(DidChangeWatchedFilesNotification.type, { watchers: [{ globPattern: '**/*' }] })
+  })
+  documents.onDidOpen(({ document }) => {
+    const file = fileOf(document.uri)
+    if (!canonical(file)) return
+    void connection.sendDiagnostics({ uri: document.uri, version: document.version, diagnostics: documentDiagnostics(document.getText()) })
+    void decks.findByFile(file)
+  })
+  documents.onDidChangeContent(({ document }) => {
+    if (canonical(fileOf(document.uri))) void connection.sendDiagnostics({ uri: document.uri, version: document.version, diagnostics: documentDiagnostics(document.getText()) })
+  })
+  documents.onDidSave(({ document }) => { const file = fileOf(document.uri); if (canonical(file)) changed([file]) })
+  documents.onDidClose(({ document }) => { const deck = decks.all().find(deck => pathToFileURL(deck.entry).href === document.uri); if (deck) publishDiagnostics(deck) })
+  connection.onDidChangeWatchedFiles(({ changes }) => changed(changes.flatMap(change => fileOf(change.uri) ?? [])))
+
+  const sourceAt = (uri: string, position: { line: number, character: number }) => {
+    const file = fileOf(uri)
+    if (!canonical(file)) return undefined
+    const document = documents.get(uri) ?? TextDocument.create(uri, 'json', 0, fileText(file))
+    const source = readDocument(document.getText())
+    const found = source.tree && source.document ? nodeAt(source.tree, document.offsetAt(position)) : undefined
+    return found && source.document ? { ...found, document, file, tree: source.tree!, content: source.document } : undefined
+  }
+  const anchorOf = async (uri: string, position: { line: number, character: number }) => {
+    const found = sourceAt(uri, position)
+    if (!found || found.path[0] !== 'blocks' || found.path.at(-1) !== 'anchor' || found.path.at(-2) !== 'origin' || found.node.type !== 'string') return undefined
+    const block = found.content.blocks[String(found.path[1])]
+    if (block?.type !== 'code') return undefined
+    const deck = await decks.findByFile(found.file)
+    if (!deck?.compilation) return undefined
+    const origin = findNodeAtLocation(found.tree, found.path.slice(0, -1)), pin = origin && getNodeValue(origin)?.pin
+    const ref: AnchorRef = { anchor: found.node.value as AnchorString, blockId: block.id, range: offsetRange(found.document, found.node.offset + 1, found.node.length - 2), ...typeof pin === 'string' ? { pin } : {} }
+    return { compilation: deck.compilation, ref, t: LS_MESSAGES[found.content.metadata.lang === 'en' ? 'en' : 'zh-CN'] }
+  }
+  connection.onDefinition(async ({ textDocument, position }) => {
+    const anchor = await anchorOf(textDocument.uri, position)
+    if (anchor) return anchorDefinition(anchor.compilation, anchor.ref)
+    const found = sourceAt(textDocument.uri, position)
+    const target = found && entityReference(found.content, found.path, found.node.value)
+    const node = target && found ? findNodeAtLocation(found.tree, target) : undefined
+    return node && found ? [{ uri: textDocument.uri, range: offsetRange(found.document, node.offset, node.length) }] : null
+  })
+  connection.onHover(async ({ textDocument, position }) => {
+    const found = await anchorOf(textDocument.uri, position)
+    return found ? anchorHover(found.compilation, found.ref, found.t) : null
+  })
+  connection.onRequest(SECTION_REQUEST, async ({ textDocument, position }: PositionParams): Promise<SectionLocation | null> => {
+    const found = sourceAt(textDocument.uri, position)
+    const id = found && sectionAtPath(found.content, found.path)
+    const section = id && found?.content.sections[id]
+    if (!found || !id || !section) return null
+    const deck = await decks.findByFile(found.file)
+    const link = deck?.compilation ? sectionLinks(webPages(deck.compilation.doc))[id] ?? '/' : '/'
+    return { entry: found.file, id, index: found.content.sectionOrder.indexOf(id) + 1, title: section.title, link }
+  })
+  connection.onRequest(PREVIEW_REQUEST, async ({ textDocument }: DocumentParams): Promise<Preview> => {
+    const file = fileOf(textDocument.uri), deck = canonical(file) ? await decks.findByFile(file) : undefined
+    if (!deck) throw new Error(`Preview requires a canonical ${DOCUMENT_ENTRY} document.`)
+    return { entry: deck.entry, url: await devServers.urlOf(deck.entry) }
+  })
+
+  connection.onShutdown(() => { for (const timer of timers.values()) clearTimeout(timer); timers.clear(); return devServers.close() })
+  process.once('exit', () => void devServers.close())
+  documents.listen(connection)
+  connection.listen()
+}