Skip to content

feat(snippet): embeddable <silk-snippet> element with live diagnostics, hover, and inlay hints - #268

Merged
julia-script merged 3 commits into
mainfrom
julia/docs-snippet-diagnostics-flag-b0850c
Aug 27, 2026
Merged

feat(snippet): embeddable <silk-snippet> element with live diagnostics, hover, and inlay hints#268
julia-script merged 3 commits into
mainfrom
julia/docs-snippet-diagnostics-flag-b0850c

Conversation

@julia-script

Copy link
Copy Markdown
Owner

Summary

Extracts the labs workbench editor into a new framework-free package, @silk-effect/snippet, exposing a <silk-snippet> custom element that any plain-HTML page can use with one script tag — and teaches the static documentation site to emit it for silk fences.

  • packages/snippet — CodeMirror-based editor core (Editor.ts) with compiler-driven highlighting and opt-in language-server semantics: diagnostics, hover, inlay-hints, editable as boolean attributes. Snippets compile lazily (first visibility, main thread) as standalone modules with doctest's conventions, so readers see exactly what doctest verified. First consumer of LspDocument.inlayHints. Shadow-DOM theming via --silk-snippet-* custom properties with light/dark defaults; hover markdown rendered by a DOM renderer (HoverContent.ts) preserving link-scheme sanitization.
  • Labs re-pointedapps/docs/app/labs/editor.tsx is now a ~90-line React wrapper over the shared core; Hover.tsx deleted. Workbench palette mapped onto the element's CSS properties; observable behavior unchanged.
  • Site emissionsilk fences render as <silk-snippet diagnostics hover>; silk,ignore degrades to a highlight-only element that never compiles; other languages keep <pre><code>. The CLI ships the self-registering bundle (2.98 MB / ~714 KB gzip) with generated output, referenced relatively; silk-snippet:not(:defined) CSS keeps no-JS pages readable.
  • Renderer boundary preservedSite.render stays pure (bundle contents as an option); only the CLI shell resolves @silk-effect/snippet/bundle as an opaque asset. The site package's dependency guard tests were deliberately amended to allowlist exactly that, per their own comments.

OpenSpec: change extract-embeddable-silk-snippet-element implemented, synced (snippet-element, documentation-site-silk-snippets capabilities), and archived.

Test plan

  • packages/snippet: 11 jsdom tests covering the spec scenarios (highlight-only never compiles, per-flag gating, doctest-parity diagnostics, unsafe hover links, read-only default, deferred compile, inlay hint widgets)
  • packages/documentation-site: 27 tests including snippet emission, ignore degradation, bundle shipping, relative references
  • Full suites green across snippet, documentation-site, docs, lsp, language; typecheck green
  • Manual pass in Chromium against a statically served generated site: highlight, pass/fail diagnostics, hover tooltip, : SystemAllocator inlay hint, editable recompile-on-edit, light + dark themes

New framework-free @silk-effect/snippet package: CodeMirror-based editor core
with compiler-driven highlighting and opt-in language-server semantics
(diagnostics, hover, inlay hints) compiled lazily in the browser per snippet,
exactly as doctest verifies them. The labs workbench editor becomes a thin
React wrapper over the shared core; Hover.tsx's React renderer is replaced by
a DOM renderer in the package. The static documentation site emits
<silk-snippet> for silk fences (silk,ignore degrades to highlight-only) and
ships the self-registering element bundle with generated pages, keeping the
renderer's no-workspace-imports boundary: only the CLI shell resolves the
bundle, as opaque file contents.
Syncs the snippet-element and documentation-site-silk-snippets capabilities
into main specs and archives the completed change.
@julia-script
julia-script merged commit 4f0a1aa into main Aug 27, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant