coc-tinymist 0.1.0 → 0.1.75

package/README.md

@@ -1,6 +1,7 @@
 # coc-tinymist
 
-Typst language support for coc.nvim powered by [Tinymist](https://github.com/Myriad-Dreamin/tinymist).
+Typst language support for [coc.nvim](https://github.com/neoclide/coc.nvim), powered by
+[Tinymist](https://github.com/Myriad-Dreamin/tinymist).
 
 ## Install
 
@@ -8,190 +9,281 @@ Typst language support for coc.nvim powered by [Tinymist](https://github.com/Myr
 :CocInstall coc-tinymist
 ```
 
-Open a `typst` buffer. If `tinymist` is not available from `tinymist.serverPath`, the extension's managed storage, or `$PATH`, coc-tinymist can download the latest Tinymist release from GitHub.
+Then open a `.typ` file. If no Tinymist executable is configured, coc-tinymist can download a managed Tinymist release on first use.
+
+## Server Setup
+
+coc-tinymist resolves the server in this order:
+
+1. `tinymist.serverPath`
+2. the extension-managed Tinymist binary
+3. `tinymist` from `$PATH`
+
+The default update mode is `prompt`: the extension asks before installing a missing managed server or updating an existing one. Use `manual`, `auto`, or `never` if you want tighter control.
+
+```jsonc
+{
+  "tinymist.updates.mode": "prompt"
+}
+```
+
+Useful server commands:
+
+```vim
+:CocCommand tinymist.install
+:CocCommand tinymist.update
+:CocCommand tinymist.useManagedServer
+:CocCommand tinymist.useSystemServer
+:CocCommand tinymist.useCustomServer
+:CocCommand tinymist.restartServer
+:CocCommand tinymist.serverVersion
+```
+
+If you already have a manual `languageserver.tinymist` entry in `coc-settings.json`, remove it or run:
+
+```vim
+:CocCommand tinymist.checkDuplicateServer
+```
 
 ## Configuration
 
-Common settings in `coc-settings.json`:
+Put settings in `:CocConfig` or a workspace `.vim/coc-settings.json`.
 
 ```jsonc
 {
-  "semanticTokens.enable": false,
-  "[typst]": {
-    "semanticTokens.enable": true
-  },
   "tinymist.enable": true,
+  "tinymist.updates.mode": "prompt",
   "tinymist.serverPath": null,
   "tinymist.serverArgs": ["lsp"],
-  "tinymist.updates.mode": "prompt",
-  "tinymist.rootPath": null,
-  "tinymist.outputPath": "",
-  "tinymist.exportTarget": "paged",
+
   "tinymist.formatterMode": "typstyle",
   "tinymist.formatterPrintWidth": 120,
-  "tinymist.fontPaths": null,
-  "tinymist.systemFonts": true,
-  "tinymist.exportPdf": "never",
+
   "tinymist.exportOnSave": [],
-  "tinymist.exportOnType": [],
-  "tinymist.exportOnIdle": [],
-  "tinymist.exportOpenAfterSave": false,
   "tinymist.exportOutputDirectory": null,
-  "tinymist.exportShowIn": "message",
-  "tinymist.lint.enabled": false,
-  "tinymist.lint.when": "onSave",
-  "tinymist.semanticTokens": "enable",
-  "tinymist.inlayHints.packageVersionStatus": true,
-  "tinymist.cocFallbackDocumentHighlight": true,
-  "tinymist.cocFallbackInlayHints": false,
-  "tinymist.fallback.maxFileBytes": 524288,
-  "tinymist.fallback.maxHighlights": 500,
-  "tinymist.fallback.maxInlayHints": 500,
-  "tinymist.onEnterEvent": false,
+
   "tinymist.compileStatus": "disable",
-  "tinymist.statusBarFormat": "{compileStatusIcon} {wordCount} [{fileName}]",
-  "tinymist.mainFile.store": "workspaceState",
-  "tinymist.tasks.workspaceFileLimit": 100,
-  "tinymist.tasks.workspaceTimeoutMs": 120000,
-  "tinymist.tasks.fileTimeoutMs": 30000,
-  "tinymist.tasks.maxOutputBytes": 1048576,
-  "tinymist.tasks.progressIntervalMs": 2000,
-  "tinymist.commands.exportTimeoutMs": 120000,
-  "tinymist.commands.profileTimeoutMs": 120000,
-  "tinymist.commands.templateTimeoutMs": 60000,
-  "tinymist.markdown.isTrusted": false,
-  "tinymist.markdown.supportHtml": false
+  "tinymist.statusBarFormat": "{compileStatusIcon} {wordCount} [{fileName}]"
 }
 ```
 
-Set `"tinymist.updates.mode": "never"` to disable managed downloads and only use a configured or system Tinymist executable. Use `"manual"` to install/update only when running `tinymist.install` or `tinymist.update`, `"prompt"` to ask first, or `"auto"` to download without prompting.
-
-Managed Tinymist downloads currently support macOS arm64/x64, Linux x64 GNU/musl, Linux arm64 GNU, Linux armv7 GNU, and Windows x64/arm64. On other platforms, install Tinymist yourself and point `tinymist.serverPath` at that executable.
-
-Set `"tinymist.compileStatus": "enable"` to opt into the status bar item for compile state, word count, and current file. Set `"tinymist.statusBarFormat": ""` to keep notifications enabled while hiding the item.
-
-Set `"semanticTokens.enable": true` under the `[typst]` language override to let Coc render semantic token highlights for Typst without enabling them globally. `tinymist.semanticTokens` controls whether Tinymist provides semantic token data to Coc; it does not override Coc's semantic highlighting gate. Use `:CocCommand semanticTokens.checkCurrent` to inspect whether Coc is applying semantic highlights in the current buffer, and `:CocCommand semanticTokens.refreshCurrent` after changing highlight groups.
+All configuration keys are contributed to Coc's JSON schema and grouped below.
+
+### Server
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `tinymist.enable` | `true` | Enable coc-tinymist. |
+| `tinymist.serverPath` | `null` | Absolute path to a Tinymist executable. When unset, coc-tinymist uses a managed binary or `$PATH`. |
+| `tinymist.serverArgs` | `["lsp"]` | Arguments passed to Tinymist. |
+| `tinymist.serverExtraEnv` | `null` | Extra environment variables for Tinymist. |
+| `tinymist.restartServerOnConfigChange` | `false` | Restart Tinymist when process-level settings change. |
+| `tinymist.trace.server` | `"off"` | Trace LSP traffic: `off`, `messages`, or `verbose`. |
+| `tinymist.updates.mode` | `"prompt"` | Managed server install/update mode: `prompt`, `auto`, `manual`, or `never`. |
+| `tinymist.updates.checkOnStartup` | `true` | Check managed server updates on startup. |
+| `tinymist.updates.prompt` | `true` | Deprecated. Use `tinymist.updates.mode` instead. |
+
+### Project and Compiler
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `tinymist.projectResolution` | `"singleFile"` | Use the focused file as the project entry or Tinymist's lock database. |
+| `tinymist.syntaxOnly` | `"auto"` | Control Tinymist syntax-only mode. |
+| `tinymist.rootPath` | `null` | Root path for Typst compilation. |
+| `tinymist.outputPath` | `""` | Tinymist output path pattern. |
+| `tinymist.exportTarget` | `"paged"` | Default Tinymist export target: `paged`, `html`, or `bundle`. |
+| `tinymist.typstExtraArgs` | `[]` | Extra Typst CLI-shaped arguments parsed by Tinymist. |
+| `tinymist.systemFonts` | `true` | Load system fonts in Tinymist's shared compiler environment. |
+| `tinymist.fontPaths` | `null` | Font files or directories for Tinymist. |
+
+### Formatting and Language Features
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `tinymist.formatterMode` | `"typstyle"` | Formatter backend: `disable`, `typstyle`, or `typstfmt`. |
+| `tinymist.formatterPrintWidth` | `120` | Soft print-width limit. |
+| `tinymist.formatterIndentSize` | `2` | Formatter indent size. |
+| `tinymist.formatterProseWrap` | `false` | Hard-wrap prose at the configured print width. |
+| `tinymist.semanticTokens` | `"enable"` | Enable Tinymist semantic token data. Coc highlighting still requires `semanticTokens.enable`. |
+| `tinymist.inlayHints.packageVersionStatus` | `true` | Show package version status hints when Coc inlay hints are enabled. |
+| `tinymist.cocFallbackDocumentHighlight` | `true` | Use Coc-side exact-match highlights only when Tinymist returns no highlights. |
+| `tinymist.cocFallbackInlayHints` | `false` | Add simple Coc-side Typst function parameter hints. |
+| `tinymist.fallback.maxFileBytes` | `524288` | Maximum document size for Coc-side fallback parsing. |
+| `tinymist.fallback.maxHighlights` | `500` | Maximum fallback document highlights per request. |
+| `tinymist.fallback.maxInlayHints` | `500` | Maximum fallback inlay hints per request. |
+| `tinymist.onEnterEvent` | `false` | Enable Coc-side Enter handling through Tinymist `experimental/onEnter`. |
+| `tinymist.typingContinueCommentsOnNewline` | `true` | Continue Typst comments when Coc-side Enter handling is enabled. |
+| `tinymist.lint.enabled` | `false` | Enable Tinymist lint diagnostics. |
+| `tinymist.lint.when` | `"onSave"` | Run linting on save or typing. |
+
+
+### Export, Tasks, and Status
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `tinymist.exportOnSave` | `[]` | Extension-side automatic exports after save. Use `true`, `"Pdf"`, or an array like `["Pdf", "Html"]`. |
+| `tinymist.exportOnType` | `[]` | Extension-side automatic exports after typing changes. |
+| `tinymist.exportOnIdle` | `[]` | Extension-side automatic exports after the document is idle. |
+| `tinymist.exportPdf` | `"never"` | Tinymist server-side PDF export trigger: `never`, `onSave`, `onType`, or `onDocumentHasTitle`. |
+| `tinymist.exportOutputDirectory` | `null` | Directory for automatic export artifacts. |
+| `tinymist.exportOpenAfterSave` | `false` | Open the first save-triggered export artifact. |
+| `tinymist.exportShowIn` | `"message"` | Show automatic export results in `none`, `message`, `output`, `quickfix`, or `open`. |
+| `tinymist.mainFile.store` | `"workspaceState"` | Persist pinned main files per workspace, or use `none` for memory-only pinning. |
+| `tinymist.tasks.workspaceFileLimit` | `100` | Maximum `.typ` files for workspace tests. |
+| `tinymist.tasks.workspaceTimeoutMs` | `120000` | Workspace task timeout. |
+| `tinymist.tasks.fileTimeoutMs` | `30000` | Per-file task timeout. |
+| `tinymist.tasks.maxOutputBytes` | `1048576` | Captured stdout/stderr limit per stream. |
+| `tinymist.tasks.progressIntervalMs` | `2000` | Minimum interval between workspace task progress updates. |
+| `tinymist.commands.exportTimeoutMs` | `120000` | Timeout for Tinymist export execute-command requests. |
+| `tinymist.commands.profileTimeoutMs` | `120000` | Timeout for Tinymist profile execute-command requests. |
+| `tinymist.commands.templateTimeoutMs` | `60000` | Timeout for Tinymist template execute-command requests. |
+| `tinymist.compileStatus` | `"disable"` | Enable compile status notifications and the status item. |
+| `tinymist.statusBarFormat` | `"{compileStatusIcon} {wordCount} [{fileName}]"` | Status item format. Set to `""` to hide the item while keeping notifications. |
+
+`tinymist.exportTo` lets you choose a format and destination. Output paths can use `{name}`, `{ext}`, `{kind}`, `{index}`, `{page}`, `{hash}`, and `{relativeDir}` placeholders:
 
-Set `"tinymist.onEnterEvent": true` to opt into coc-tinymist's insert-mode Enter handler for comment and equation continuation. Document-highlight fallback only runs when Tinymist returns no highlights. Inlay fallback is off by default because it is additive to Tinymist's own hints; enable it with `tinymist.cocFallbackInlayHints`. Fallback parsing is cached per document version and skipped above `tinymist.fallback.maxFileBytes`; per-request result caps are controlled by `tinymist.fallback.maxHighlights` and `tinymist.fallback.maxInlayHints`.
+```jsonc
+{
+  "tinymist.outputPath": "build/{relativeDir}/{name}-{page}.{ext}"
+}
+```
 
-The schema also includes Tinymist project resolution, syntax-only mode, formatter indent/prose wrapping, `typstExtraArgs`, and `typingContinueCommentsOnNewline`. VS Code-only settings such as webview preview, drag/drop, and paste handling are intentionally omitted.
+If a multi-file export targets `slides.png`, coc-tinymist writes `slides.png`, `slides-2.png`, `slides-3.png`, and so on.
 
-Markdown returned by Tinymist is untrusted and raw HTML rendering is disabled by default. Set `"tinymist.markdown.isTrusted": true` only if you want command links in server-provided Markdown to be executable. Set `"tinymist.markdown.supportHtml": true` only if you trust documentation generated from the current project and installed packages.
+### Markdown Trust
 
-`tinymist.exportTo` now attempts to pass a literal `outputPath` option through Tinymist's `workspace/executeCommand` export call. If the server ignores or rejects that option, coc-tinymist finalizes the result itself. Path artifacts are copied through temporary sibling files and atomically renamed into place where the platform allows it; inline `data` artifacts are written the same way. If a multi-file export targets `slides.png`, coc-tinymist writes `slides.png`, `slides-2.png`, `slides-3.png`, and so on. If the target has no extension, it is treated as a directory and Tinymist-generated basenames are preserved when available.
+| Setting | Default | Description |
+| --- | --- | --- |
+| `tinymist.markdown.isTrusted` | `false` | Trust Markdown returned by Tinymist. Enable only if you want command links in server-provided Markdown to run. |
+| `tinymist.markdown.supportHtml` | `false` | Render raw HTML in Tinymist Markdown. Enable only for trusted projects and packages. |
 
-Export target paths may use `{name}`, `{ext}`, `{kind}`, `{index}`, `{page}`, `{hash}`, and `{relativeDir}` placeholders. For example, `build/{relativeDir}/{name}-{hash}-{page}.{ext}` keeps artifacts from different source folders from colliding.
+## Commands
 
-For extension-side automatic exports, set `tinymist.exportOnSave`, `tinymist.exportOnType`, or `tinymist.exportOnIdle` to `true` for PDF, a single format such as `"Pdf"`, or an array such as `["Pdf", "Html"]`. Use `tinymist.exportOutputDirectory` to relocate automatic export artifacts, `tinymist.exportOpenAfterSave` to open save-triggered artifacts, and `tinymist.exportShowIn` to choose `none`, `message`, `output`, `quickfix`, or `open`.
+Run commands with `:CocCommand`.
 
-Automatic exports are serialized per source file, output format, and target path. If another save/type/idle event arrives while an export is running, coc-tinymist reruns once after the active export finishes so the final document state is not dropped.
+### Server and Config
 
-Pinned main documents are stored per workspace by default with `tinymist.mainFile.store: "workspaceState"` and restored after server startup/restart. Set it to `"none"` for in-memory-only pinning. `tinymist.detectMain` ranks obvious candidates such as `main.typ`, `thesis.typ`, `paper.typ`, Typst manifest entry points, and files with document setup rules.
+| Command | Description |
+| --- | --- |
+| `tinymist.actions` | Pick from grouped Tinymist actions. |
+| `tinymist.restartServer` | Restart the Tinymist language server. |
+| `tinymist.install` | Install Tinymist from GitHub releases. |
+| `tinymist.update` | Check for and install a managed Tinymist update. |
+| `tinymist.serverVersion` | Show the active Tinymist version and source. |
+| `tinymist.showStatus` | Show the latest Tinymist status details. |
+| `tinymist.showLog` | Open the Tinymist language server log. |
+| `tinymist.doctor` | Open a diagnostic report for server, config, workspace, and status. |
+| `tinymist.doctorCopyIssueTemplate` | Copy a sanitized issue report to the clipboard. |
+| `tinymist.doctorSaveReport` | Save a sanitized doctor report to a temp file. |
+| `tinymist.checkDuplicateServer` | Check for a duplicate manual `languageserver.tinymist` config. |
+| `tinymist.openConfig` | Open user `coc-settings.json`. |
+| `tinymist.openWorkspaceConfig` | Open or create workspace `.vim/coc-settings.json`. |
+| `tinymist.explainConfig` | Show resolved server, client, and Coc-only config. |
+| `tinymist.migrateConfig` | Copy legacy Tinymist config keys to current coc-tinymist keys. |
+| `tinymist.resetManagedServer` | Remove the managed Tinymist binary and release metadata. |
+| `tinymist.useManagedServer` | Clear `serverPath` and use the managed Tinymist binary. |
+| `tinymist.useSystemServer` | Point `serverPath` at `tinymist` from `$PATH`. |
+| `tinymist.useCustomServer` | Prompt for a custom Tinymist executable path. |
+
+### Export and Documents
 
-File-sensitive commands such as export, test, profile, template insertion, and pin-current-main require a file-backed Typst buffer. Coverage task results only attach `target/coverage.json` when the report was written during the current coverage run.
+| Command | Description |
+| --- | --- |
+| `tinymist.export` | Pick an export format for the current Typst document. |
+| `tinymist.exportTo` | Pick a format and relocate the generated artifact. |
+| `tinymist.exportAndOpen` | Pick a format and open the generated artifact. |
+| `tinymist.exportRepeat` | Repeat the last Tinymist export. |
+| `tinymist.exportCopyPath` | Copy the first path from the last export result. |
+| `tinymist.exportCurrentPdf` | Export the current document as PDF. |
+| `tinymist.exportCurrentSvg` | Export the current document as SVG. |
+| `tinymist.exportCurrentPng` | Export the current document as PNG. |
+| `tinymist.exportCurrentHtml` | Export the current document as HTML. |
+| `tinymist.exportCurrentMarkdown` | Export the current document as Markdown. |
+| `tinymist.exportCurrentText` | Export the current document as text. |
+| `tinymist.profileCurrentFile` | Write current document trace data to a temp JSON file and the Tinymist Commands output channel. |
+| `tinymist.onEnter` | Run Tinymist's experimental on-enter edit for comments/equations. |
+
+### Main Document
 
-CLI-backed tasks respect `tinymist.tasks.workspaceFileLimit`, `tinymist.tasks.workspaceTimeoutMs`, `tinymist.tasks.fileTimeoutMs`, `tinymist.tasks.maxOutputBytes`, and `tinymist.tasks.progressIntervalMs`. Use `tinymist.taskCancelRunning` to abort running CLI-backed task subprocesses. LSP command-backed export/profile/template actions use `tinymist.commands.exportTimeoutMs`, `tinymist.commands.profileTimeoutMs`, and `tinymist.commands.templateTimeoutMs`.
+| Command | Description |
+| --- | --- |
+| `tinymist.pinCurrentAsMain` | Pin the current Typst document as main. |
+| `tinymist.selectMain` | Pick a Typst file to pin as main. |
+| `tinymist.detectMain` | Detect likely main files such as `main.typ`, `thesis.typ`, manifest entries, and setup files. |
+| `tinymist.showMain` | Show the pinned main file. |
+| `tinymist.clearMain` | Clear the pinned main file. |
 
-Server source commands such as `tinymist.useManagedServer`, `tinymist.useSystemServer`, and `tinymist.useCustomServer` prompt for the configuration scope before writing `tinymist.serverPath`: Global, Workspace, or Workspace Folder.
+### Templates
 
-## Commands
+| Command | Description |
+| --- | --- |
+| `tinymist.showTemplateGallery` | Open `:CocList tinymistTemplates`. |
+| `tinymist.refreshTemplates` | Refresh the Typst Universe template cache. |
+| `tinymist.initTemplate` | Initialize a Typst project from a template package spec. |
+| `tinymist.initTemplateVersion` | Pick a template and initialize a specific version. |
+| `tinymist.initTemplateInPlace` | Insert a template entry file at the cursor. |
 
-Use these with `:CocCommand`:
+### Tasks and Diagnostics
 
 | Command | Description |
 | --- | --- |
-| `tinymist.restartServer` | Restart the Tinymist language server |
-| `tinymist.install` | Install Tinymist from the latest GitHub release |
-| `tinymist.update` | Check for and install the latest managed Tinymist release |
-| `tinymist.serverVersion` | Show the active Tinymist version |
-| `tinymist.doctor` | Open a diagnostic report for server, config, workspace, and status |
-| `tinymist.doctorCopyIssueTemplate` | Copy a sanitized markdown issue report to the clipboard |
-| `tinymist.doctorSaveReport` | Save a sanitized markdown doctor report to a temp file |
-| `tinymist.checkDuplicateServer` | Check for a duplicate manual `languageserver.tinymist` config |
-| `tinymist.openConfig` | Open the user `coc-settings.json` file |
-| `tinymist.openWorkspaceConfig` | Open or create `.vim/coc-settings.json` under the current workspace |
-| `tinymist.explainConfig` | Show resolved Tinymist server config, client flags, and Coc-only settings |
-| `tinymist.migrateConfig` | Copy legacy Tinymist config keys to current coc-tinymist keys |
-| `tinymist.resetManagedServer` | Remove the managed Tinymist binary and release metadata |
-| `tinymist.useSystemServer` | Point `tinymist.serverPath` at the Tinymist executable found on `$PATH` |
-| `tinymist.useManagedServer` | Clear `tinymist.serverPath` and use the managed Tinymist binary |
-| `tinymist.useCustomServer` | Prompt for a custom Tinymist executable path |
-| `tinymist.actions` | Pick from grouped Tinymist actions for export, tasks, main files, templates, diagnostics, server, and config |
-| `tinymist.showStatus` | Show the latest Tinymist status details |
-| `tinymist.showLog` | Show the Tinymist language server log |
-| `tinymist.showTemplateGallery` | Open `CocList tinymistTemplates` |
-| `tinymist.refreshTemplates` | Refresh the Typst Universe template cache |
-| `tinymist.initTemplate` | Initialize a Typst project from a template package spec |
-| `tinymist.initTemplateVersion` | Pick a template and initialize a specific version |
-| `tinymist.initTemplateInPlace` | Insert a template entry file at the cursor |
-| `tinymist.export` | Pick an export format for the current Typst document |
-| `tinymist.exportTo` | Pick an export format and relocate the generated artifact to an output path |
-| `tinymist.exportAndOpen` | Pick an export format and open the generated artifact |
-| `tinymist.exportRepeat` | Repeat the last Tinymist export with the same format and options |
-| `tinymist.exportCopyPath` | Copy the first path from the last Tinymist export result |
-| `tinymist.exportCurrentPdf` | Export the current Typst document as PDF |
-| `tinymist.exportCurrentSvg` | Export the current Typst document as SVG |
-| `tinymist.exportCurrentPng` | Export the current Typst document as PNG |
-| `tinymist.exportCurrentHtml` | Export the current Typst document as HTML |
-| `tinymist.exportCurrentMarkdown` | Export the current Typst document as Markdown |
-| `tinymist.exportCurrentText` | Export the current Typst document as text |
-| `tinymist.profileCurrentFile` | Write current document trace data to a temp JSON file and the Tinymist Commands output channel |
-| `tinymist.pinCurrentAsMain` | Pin the current Typst document as main |
-| `tinymist.selectMain` | Pick a Typst file to pin as main |
-| `tinymist.showMain` | Show the currently pinned main file tracked by coc-tinymist |
-| `tinymist.clearMain` | Clear the pinned Tinymist main file |
-| `tinymist.detectMain` | Detect likely main Typst files and pin the selected candidate |
-| `tinymist.testCurrent` | Run `tinymist test` for the current file and record the task result |
-| `tinymist.testWorkspace` | Run `tinymist test` for Typst files under the workspace, capped at 100 files |
-| `tinymist.coverageCurrent` | Run `tinymist test --coverage` for the current file and record the task result plus `target/coverage.json` when produced |
-| `tinymist.tasks` | Open the Tinymist task history list |
-| `tinymist.taskRerunLast` | Rerun the most recent rerunnable Tinymist task |
-| `tinymist.taskOpenLastOutput` | Open the output view for the most recent Tinymist task |
-| `tinymist.taskClearHistory` | Clear structured Tinymist task history |
-| `tinymist.taskCancelRunning` | Cancel running CLI-backed Tinymist tasks |
-| `tinymist.lintToLocationList` | Populate the location list from current Typst/Tinymist diagnostics |
-| `tinymist.coverageOpenReport` | Open the latest Tinymist coverage report artifact |
-| `tinymist.onEnter` | Run Tinymist's experimental on-enter edit for comments/equations |
+| `tinymist.testCurrent` | Run `tinymist test` for the current file. |
+| `tinymist.testWorkspace` | Run `tinymist test` for Typst files under the workspace. |
+| `tinymist.coverageCurrent` | Run `tinymist test --coverage` for the current file. |
+| `tinymist.coverageOpenReport` | Open the latest Tinymist coverage report artifact. |
+| `tinymist.tasks` | Open the Tinymist task history list. |
+| `tinymist.taskRerunLast` | Rerun the most recent rerunnable Tinymist task. |
+| `tinymist.taskOpenLastOutput` | Open the output view for the most recent Tinymist task. |
+| `tinymist.taskClearHistory` | Clear structured Tinymist task history. |
+| `tinymist.taskCancelRunning` | Cancel running CLI-backed Tinymist tasks. |
+| `tinymist.lintToLocationList` | Populate the location list from current Typst/Tinymist diagnostics. |
 
 ## Lists
 
-Use these with `:CocList`:
+Run lists with `:CocList`.
 
 | List | Description |
 | --- | --- |
-| `tinymistTemplates` | Browse Typst Universe templates and initialize or insert one |
-| `tinymistTasks` | Inspect task history, rerun tasks, open artifacts, copy commands, and populate the location list |
-| `tinymistExports` | Inspect export history, open artifacts, copy paths, repeat exports, or relocate an export |
-
-The template list fetches `https://packages.typst.org/preview/index.json` and filters packages with template metadata. The latest successful gallery response is cached in Coc global state for offline browsing. If the network is unavailable and no cache exists, `tinymist.initTemplate` and `tinymist.initTemplateInPlace` still accept a manually entered package spec. The list actions include `init`, `in-place`, `details`, `version`, and `refresh`.
+| `tinymistTemplates` | Browse Typst Universe templates and initialize or insert one. |
+| `tinymistTasks` | Inspect task history, rerun tasks, open artifacts, copy commands, and populate the location list. |
+| `tinymistExports` | Inspect export history, open artifacts, copy paths, repeat exports, or relocate an export. |
 
-Task runs are stored in memory as structured records with command, target, timestamps, status, raw result, message, and artifact paths. The task list actions are `open-output`, `rerun`, `copy-command`, `clear`, `open-artifact`, and `populate-location-list`; long CLI-backed tasks can be cancelled with `tinymist.taskCancelRunning`. `tinymist.lintToLocationList` uses the current Coc diagnostics because Tinymist lint feedback is delivered through LSP diagnostics rather than a separate one-shot command. The export list actions are `open`, `reveal/copy-path`, `repeat`, and `export-to`.
+The template gallery fetches `https://packages.typst.org/preview/index.json` and caches the latest successful response in Coc global state. If the network is unavailable and no cache exists, `tinymist.initTemplate` and `tinymist.initTemplateInPlace` still accept a manually entered package spec.
 
 ## Troubleshooting
 
-Run `:CocCommand tinymist.doctor` first. For issue reports, prefer `:CocCommand tinymist.doctorCopyIssueTemplate`; it redacts proxy credentials, token-like environment keys and values, and configured paths where possible.
+Start with:
 
-If `tinymist.serverPath` is wrong or stale, coc-tinymist keeps the extension loaded and reports the invalid path. Run `:CocCommand tinymist.useManagedServer`, `:CocCommand tinymist.useSystemServer`, or `:CocCommand tinymist.useCustomServer` to repair the server source, then run `:CocCommand tinymist.restartServer`.
-
-If managed install says your platform is unsupported, install Tinymist manually and set `tinymist.serverPath`. Managed downloads currently cover the platforms listed above, not every target that Tinymist may publish.
+```vim
+:CocCommand tinymist.doctor
+```
 
-If you are behind a corporate proxy, configure Coc's `http.proxy` and `http.proxyStrictSSL` settings. Managed release metadata, checksums, binary downloads, and the Typst Universe template gallery all use those proxy settings.
+For issue reports, prefer:
 
-If Tinymist appears to start twice or diagnostics/actions duplicate, run `:CocCommand tinymist.checkDuplicateServer` and remove any manual `languageserver.tinymist` entry from `coc-settings.json`.
+```vim
+:CocCommand tinymist.doctorCopyIssueTemplate
+```
 
-If commands say Tinymist is not running, run `:CocCommand tinymist.showLog`, `:CocCommand tinymist.showStatus`, and `:CocCommand tinymist.doctor`. Then try `:CocCommand tinymist.restartServer`.
+The copied report redacts proxy credentials, token-like environment keys and values, and configured paths where possible.
 
-If an export succeeds but reports no artifact path, open the `Tinymist Commands` output channel. Some server responses may return inline data or no path; `tinymist.exportTo` is the most predictable command when you need a specific artifact path.
+Common fixes:
 
-If `tinymist.coverageOpenReport` finds no report, rerun `:CocCommand tinymist.coverageCurrent`. coc-tinymist intentionally ignores stale `target/coverage.json` files that were not produced by the current coverage run.
+- Wrong or stale server path: run `tinymist.useManagedServer`, `tinymist.useSystemServer`, or `tinymist.useCustomServer`, then restart.
+- Duplicate diagnostics/actions: run `tinymist.checkDuplicateServer` and remove any manual `languageserver.tinymist` config.
+- Managed download behind a proxy: configure Coc's `http.proxy` and `http.proxyStrictSSL`; managed downloads and template gallery requests use those settings.
+- Command says Tinymist is not running: run `tinymist.showLog`, `tinymist.showStatus`, and `tinymist.doctor`, then restart.
+- Export succeeds without a visible artifact path: open the `Tinymist Commands` output channel, or use `tinymist.exportTo` when you need a specific destination.
+- Coverage report is missing: rerun `tinymist.coverageCurrent`; stale `target/coverage.json` files are ignored.
+- Enter handling does nothing: set `"tinymist.onEnterEvent": true`.
 
-The on-enter keymap is disabled by default. Set `"tinymist.onEnterEvent": true` to enable it.
+File-sensitive commands such as export, test, profile, template insertion, and pin-current-main require a file-backed Typst buffer.
 
-## Development QA
+VS Code-only Tinymist settings such as webview preview, drag/drop, and paste handling are intentionally omitted.
 
-Run these before publishing:
+## Development
 
 ```sh
+npm install
 npm run typecheck
 npm test
 npm run qa:commands
@@ -200,18 +292,23 @@ npm run qa:lsp
 npm pack --dry-run
 ```
 
-`npm test` builds the extension and runs unit tests, lifecycle integration tests, mocked Coc-host tests, downloader/archive tests, export tests, activation tests, and a fake Tinymist LSP smoke test. `npm run qa:coc` runs a headless Neovim/Coc smoke test that loads this extension, checks contributed commands/lists, and runs core commands. `npm run qa:lsp` runs the real Tinymist LSP smoke test when `tinymist` is available on `$PATH` or `TINYMIST_BIN` is set.
+`npm test` builds the extension and runs unit, lifecycle, server manager, update manager, export, activation, mocked Coc-host, downloader, and fake Tinymist LSP tests.
+
+`npm run qa:coc` runs a headless Neovim/Coc smoke test that loads this extension and checks contributed commands/lists. `npm run qa:lsp` runs the real Tinymist LSP smoke test when `tinymist` is on `$PATH` or `TINYMIST_BIN` is set.
 
-For a manual release smoke, open `fixtures/sample.typ` in Neovim with Coc enabled and verify:
+For a manual smoke test, open `fixtures/sample.typ` in Neovim with Coc enabled and check:
+
+```vim
+:CocCommand tinymist.serverVersion
+:CocCommand tinymist.doctor
+:CocCommand tinymist.exportCurrentPdf
+:CocCommand tinymist.showStatus
+:CocList tinymistExports
+:CocList tinymistTasks
+:CocList tinymistTemplates
+```
 
-- `:CocCommand tinymist.serverVersion`
-- `:CocCommand tinymist.doctor`
-- `:CocCommand tinymist.exportCurrentPdf`
-- `:CocCommand tinymist.showStatus`
-- `:CocList tinymistExports`
-- `:CocList tinymistTasks`
-- `:CocList tinymistTemplates`
-- standard Coc LSP actions such as hover, definition, references, rename, formatting, code actions, diagnostics, document symbols, and semantic tokens
+Also verify standard Coc LSP actions such as hover, definition, references, rename, formatting, code actions, diagnostics, document symbols, and semantic tokens.
 
 ## License
 
@@ -219,4 +316,4 @@ MIT
 
 ---
 
-This extension is built with [create-coc-extension](https://github.com/fannheyward/create-coc-extension) and follows patterns from [coc-texlab](https://github.com/fannheyward/coc-texlab) and [coc-rust-analyzer](https://github.com/fannheyward/coc-rust-analyzer).
+Built with [create-coc-extension](https://github.com/fannheyward/create-coc-extension) and following Coc extension README conventions from [coc-texlab](https://github.com/fannheyward/coc-texlab) and [coc-rust-analyzer](https://github.com/fannheyward/coc-rust-analyzer).

package/lib/index.js

@@ -8183,6 +8183,12 @@ var TINYMIST_SETTING_DESCRIPTORS = [
     scope: "local",
     description: "Enable Coc-side inlay hint fallback."
   },
+  {
+    key: "completion.suppressBareHash",
+    defaultValue: true,
+    scope: "local",
+    description: "Suppress Tinymist completions at a standalone bare #."
+  },
   {
     key: "fallback.maxFileBytes",
     defaultValue: 524288,
@@ -8653,6 +8659,9 @@ var Config = class {
   get markdownSupportHtml() {
     return this.cfg.get("markdown.supportHtml", false);
   }
+  get completionSuppressBareHash() {
+    return this.cfg.get("completion.suppressBareHash", true);
+  }
   get exportOnSave() {
     return readExportKinds(this.cfg.get("exportOnSave", []));
   }
@@ -9969,6 +9978,125 @@ var BinaryResolver = class {
 
 // src/client/index.ts
 var import_coc17 = require("coc.nvim");
+
+// src/features/completion.ts
+function filterTinymistCompletions(document2, position, result, options = {}) {
+  if (!result) {
+    return result;
+  }
+  const linePrefix = lineTextBeforePosition(document2, position);
+  if ((options.suppressBareHash ?? true) && shouldSuppressBareHashCompletion(linePrefix)) {
+    return emptyCompletionResult(result);
+  }
+  if (!isCitationLabelCompletionContext(linePrefix)) {
+    return result;
+  }
+  return mapCompletionItems(result, dedupeCitationCompletions);
+}
+function shouldSuppressBareHashCompletion(linePrefix) {
+  return /(^|[^A-Za-z0-9_])#$/.test(linePrefix);
+}
+function isCitationLabelCompletionContext(linePrefix) {
+  return /#cite\s*\([^)\n]*<[^>\s,;)\]]*$/.test(linePrefix);
+}
+function dedupeCitationCompletions(items) {
+  const output = [];
+  const seen = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = citationCompletionKey(item);
+    if (!key) {
+      output.push(item);
+      continue;
+    }
+    const index = seen.get(key);
+    if (index === void 0) {
+      seen.set(key, output.length);
+      output.push(item);
+      continue;
+    }
+    if (citationCompletionScore(item, key) > citationCompletionScore(output[index], key)) {
+      output[index] = item;
+    }
+  }
+  return output;
+}
+function lineTextBeforePosition(document2, position) {
+  try {
+    return document2.getText({
+      start: { line: position.line, character: 0 },
+      end: position
+    });
+  } catch {
+    return "";
+  }
+}
+function mapCompletionItems(result, map) {
+  if (Array.isArray(result)) {
+    return map(result);
+  }
+  return {
+    ...result,
+    items: map(result.items)
+  };
+}
+function emptyCompletionResult(result) {
+  if (Array.isArray(result)) {
+    return [];
+  }
+  return {
+    ...result,
+    isIncomplete: false,
+    items: []
+  };
+}
+function citationCompletionKey(item) {
+  return normalizeCitationKey(completionInsertText(item)) ?? normalizeCitationKey(item.filterText) ?? normalizeCitationKey(item.label);
+}
+function completionInsertText(item) {
+  const textEdit = item.textEdit;
+  if (typeof textEdit?.newText === "string") {
+    return textEdit.newText;
+  }
+  if (typeof item.textEditText === "string") {
+    return item.textEditText;
+  }
+  if (typeof item.insertText === "string") {
+    return item.insertText;
+  }
+  return item.label;
+}
+function normalizeCitationKey(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  let key = value.trim();
+  if (key.startsWith("@")) {
+    key = key.slice(1);
+  }
+  key = key.replace(/^<+/, "").replace(/>+$/, "");
+  if (!key || /[\s()[\]{},"']/.test(key)) {
+    return void 0;
+  }
+  return key;
+}
+function citationCompletionScore(item, key) {
+  let score = 0;
+  if (normalizeCitationKey(item.label) === key) {
+    score += 100;
+  }
+  if (normalizeCitationKey(item.filterText) === key) {
+    score += 30;
+  }
+  if (normalizeCitationKey(completionInsertText(item)) === key) {
+    score += 20;
+  }
+  if (item.label.length <= key.length + 2) {
+    score += 10;
+  }
+  return score;
+}
+
+// src/client/index.ts
 function getWorkspaceRoot() {
   if (import_coc17.workspace.workspaceFolders.length) {
     return import_coc17.Uri.parse(import_coc17.workspace.workspaceFolders[0].uri).fsPath;
@@ -10080,6 +10208,12 @@ function createClient(bin, config2) {
           return Array.isArray(result) ? patchWorkspaceConfiguration(sections, result, getTinymistRuntimeConfig(config2)) : result;
         }
       },
+      async provideCompletionItem(document2, position, completionContext, token, next) {
+        const result = await next(document2, position, completionContext, token);
+        return filterTinymistCompletions(document2, position, result, {
+          suppressBareHash: config2.completionSuppressBareHash
+        });
+      },
       async provideCodeActions(document2, range, actionContext, token, next) {
         const params = {
           textDocument: { uri: document2.uri },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coc-tinymist",
-  "version": "0.1.0",
+  "version": "0.1.75",
   "description": "Typst language support for coc.nvim powered by Tinymist",
   "author": "SeniorMars <cjh16@rice.edu>",
   "license": "MIT",
@@ -504,6 +504,11 @@
           "default": false,
           "markdownDescription": "Enable coc-tinymist's opt-in inlay hint fallback for simple local Typst function parameter names. This provider is additive to Tinymist's inlay hints."
         },
+        "tinymist.completion.suppressBareHash": {
+          "type": "boolean",
+          "default": true,
+          "markdownDescription": "Suppress Tinymist completions at a standalone bare `#`. Set to `false` to show Tinymist's full bare-`#` completion list."
+        },
         "tinymist.fallback.maxFileBytes": {
           "type": "number",
           "default": 524288,