Skip to content

Narrated films for every docs page, and the bugs filming found - #392

Merged
MelbourneDeveloper merged 1 commit into
mainfrom
feature/narrated-doc-films
Oct 18, 2026
Merged

MelbourneDeveloper merged 1 commit into
mainfrom
feature/narrated-doc-films

Conversation

@MelbourneDeveloper

Copy link
Copy Markdown
Collaborator

TLDR

Every docs page with a feature to show now opens on a narrated film of the real extension, captioned in en/ja/zh. Three bugs the filming exposed are fixed test-first.

Details

Films. There are 14 new films, and the leak film is reshot with narration. Each is published as MP4 (AAC) and WebM (Opus) in LFS, with a WebP poster and .en/.ja/.zh.vtt captions. Each is catalogued in videos.json and placed after its page's introduction in all three languages:

Page Film Length
Getting Started getting-started (replaces sharplsp-tour on this page; the blog keeps it) 1:04
Editor Setup editor-setup 0:41
Configuration configuration: sharplsp.toml with monorepo mode → SLSPC0101 0:51
F# Language Support fsharp-language (the page also keeps profiler-fsharp) 1:53
Code Completions code-completions 1:09
Hover hover 1:15
Go to Definition navigation 1:00
Diagnostics diagnostics 1:24
Refactoring refactoring 1:27
Context Menus context-menus 1:10
NuGet nuget (installs FsToolkit.ErrorHandling into the F# project) 1:18
Profiler profiler-csharp (replaces profiler-film at the top; home and blog keep it) 2:16
Fix a Memory Leak profiler-fix-memory-leak, now narrated and on the layered retention graph 1:32
Architecture architecture: the host log routing an F# hover to FCS and a C# hover to Roslyn, then tree-sitter folding 0:38
Contributing contributing 0:38

The Zed page has no film. Filming a native Metal app would mean recording the real desktop through OS permissions. [WEB-DESIGN-MEDIA] now says so.

The language films run on the new demos/Shop.slnx, which holds the C# Storefront and the F# FsStorefront in one solution. F# is shown first. Catalog.Generate gains an XML doc comment for the hover film.

Bug fixes (each with a failing test first).

  • FSharpProjectLoading.buildProjectOptions passed every source file to GetProjectOptionsFromCommandLineArgs and also set SourceFiles. FCS compiled each file twice, so every single-target F# project without a C# reference showed FS3551 ("already appeared in the compilation list") on every source. Sources now go in SourceFiles only.
  • sort_members::build_edits copied each member's leading blank lines and also added its own separators, which left two or three blank lines between members. The reordered text is now built by reordered_text/leading_layout. A type whose members are separated by blank lines keeps exactly one between each; a compact type stays compact, with one blank line only where a new accessibility/category group starts. CRLF is preserved.
  • NuGet browser buildDetailsHtml: the version picker beside Install selected nothing, so it showed the newest listed version (often a prerelease such as 6.0.0-beta003), while Install sends the search result's stable version. It now shows installedVersion ?? version.

Film kit (src/website/tools/profiler-film/, see its README).

  • New acts:
    • kit/acts/language.mjs: LANGUAGE settings, prepareCode/warm, scene(clip, step, caption, act, { speed, retries }), complete, quickFix, renameTo, navigate (fails the take on "No definition found"), peekReferences, hoverEach, settingsEditor;
    • kit/acts/shop.mjs: moves on the Shop demo shared by several films, plus ready(...);
    • kit/acts/explorer.mjs: Solution Explorer context menus;
    • kit/acts/tour.mjs: profilerTour, now used by both profiler films;
    • kit/code.mjs: finds a word on a line on screen, and hovers or clicks it.
  • overlay.pointAt: a pointer that glides to what the film acts on. Stills hide it, as they hide the caption.
  • Sets: SHOP, and REPO (a git archive of HEAD and lspkit, opened with the extension disabled). A film can supply its own workspace settings. A failed shoot copies the editor's logs to out/<film>/logs.
  • Privacy:
    • demos, the editor profile and temp files live under /tmp;
    • the editor runs with --force-disable-user-env, on a copy-on-write clone of the .NET install at /tmp/sharplsp-film-dotnet, so the SDK path and any command a terminal prints are neutral;
    • the demo app shares that temp folder, so the profiler can still attach;
    • context menus render in the workbench (window.menuStyle: custom).
  • voice.mjs loads kokoro-js only when it speaks. Its phonemizer used to print its own source over any failed shoot.
  • [WEB-DESIGN-MEDIA] covers the language films, the narrated walkthrough on every page, and when a terminal may appear: F# Interactive, a build task, or a shell with no profile and a bare $ prompt.

Docs. The architecture page (en/ja/zh) now says a restarted sidecar does not yet reload its workspace (#386).

Issues filed for bugs found but not fixed here: #386 (restarted sidecar not rehydrated), #387 (F# F12 on a module-qualified call right after load), #388 (F# hover lacks .NET XML docs), #389 (F# inlay-hint layout), #390 (no DiagnosticTag.Unnecessary), #391 (metadata as source decompiles reference assemblies).

How Do The Automated Tests Prove It Works?

  • F#, double compile: FSharpProjectCrackingTests › hand-built options name each source once, so FCS never sees a file twice failed before the fix (the source was in OtherOptions). It now passes. It also checks the project with ParseAndCheckProject and asserts no FS3551 and no diagnostics at all. The full F# sidecar suite passes, 440/440.
  • F# navigation coverage: FSharpNavigationEdgeTests › definition of a module-qualified call lands in the declaring file the editor never opened (passes; F#: Go to Definition on Checkout.checkout finds nothing until Checkout.fs has been opened #387 still needs the editor's fresh-session state reproduced).
  • Sort Members: sort_members_extra › test_sort_members_keeps_one_blank_line_between_members and test_sort_members_keeps_compact_members_compact both failed before the fix ("\n\n\n\n"; blank lines added to a compact type) and now pass. All 16 sort-members e2e tests and the 6 unit tests pass, and clippy is clean.
  • NuGet: NuGet Browser — pure html › buildHtml details panel shows the version Install installs, not the newest prerelease failed before the fix ("the picker shows the version Install sends") and now passes (20/20). npm run lint passes: prettier, eslint and tsc.
  • Website: all of npx playwright test passes locally: 604 passed and 11 skipped, the skips by layout.
    • site-videos.spec.js, every docs page in every language:
      • plays its film, served with a poster;
      • carries a VideoObject that matches the player's label;
      • plays the film unmuted, with en/ja/zh text/vtt tracks and the page's language as default;
      • never autoplays.
    • profiler-media.spec.js: the Profiler page now opens on the profiler-csharp poster.
  • Duplication: deslop . reports 6.5% (6.6% before), under the 6.65% threshold.

Every docs page with a feature to show now opens on a narrated walkthrough of
the real extension, captioned in English, Japanese and Chinese: getting
started, editor setup, configuration, F# language support, completions, hover,
navigation, diagnostics, refactoring, context menus, NuGet, the profiler (a C#
tour), memory leaks (now narrated, on the layered retention graph),
architecture and contributing. The language films run on demos/Shop.slnx, C#
and F# in one solution, and show F# first.

Bugs the cameras found, each fixed test-first:
- F#: hand-built project options put every source file on the FCS command line
  as well as in SourceFiles, so FCS compiled each file twice and every F#
  project showed FS3551 warnings.
- Sort Members kept each member's own blank lines and added its own, leaving
  two or three blank lines between members.
- NuGet: the version picker beside Install showed the newest listed version,
  often a prerelease, not the version Install sends.

The film kit gains language acts (completion, quick fixes, rename,
navigation, the Solution Explorer), a gliding pointer, retried takes, logs
kept from a failed shoot, and a neutral environment: staging, temp files and a
cloned .NET install under /tmp, with the login shell's environment off, so no
home path reaches a frame.
@MelbourneDeveloper
MelbourneDeveloper enabled auto-merge (squash) October 18, 2026 13:19
@MelbourneDeveloper
MelbourneDeveloper merged commit 99b3203 into main Oct 18, 2026
57 checks passed
@MelbourneDeveloper
MelbourneDeveloper deleted the feature/narrated-doc-films branch October 18, 2026 13:48
MelbourneDeveloper added a commit that referenced this pull request Oct 19, 2026
## TLDR
Website films play in Windows Chrome and Edge again: every video lists
its H.264 MP4 before its VP9 WebM, and a new playback test proves frames
actually decode.

## Details
- **Root cause.** Windows Chrome/Edge accept the VP9 `<source>`, decode
one frame, then stop with `PIPELINE_ERROR_DECODE`, and never try the
next source. Every film listed WebM first, so every film failed there.
- **`src/_data/videos.json`**: all 18 films now list `["mp4", "webm"]`.
- **`video-figure.js`**: the VideoObject `contentUrl` points to the
first (preferred) encoding instead of the last, so search engines link
the MP4.
- **New `tests/video-playback.spec.js`**: plays 20 films across docs and
blog pages, then pauses, seeks to the middle and resumes. Each step
checks that the clock advances, frames decode
(`getVideoPlaybackQuality().totalVideoFrames`) and `video.error` stays
null. A served file and a resolved `play()` don't prove playback.
- **`tests/media.js`**: a new `expectFramesAdvance` helper, which also
catches decode errors raised after `play()` resolves.
- **`playwright.config.js`**: on Windows, the playback spec also runs on
installed Chrome and Edge, where the bug reproduced; bundled Chromium
and WebKit passed. The phone projects use installed Chrome there because
Windows WebKit rejects known-good H.264.
- **`docs/specs/DESIGN-SYSTEM.md` [WEB-DESIGN-MEDIA]** records the
MP4-first rule and the playback-test requirement.
- **Test expectations** in `profiler-media.spec.js` and
`site-videos.spec.js` now expect MP4 first.
- **Branch housekeeping.** This branch also merges the stale branches
`feature/narrated-doc-films`, `feature/doc-stills` and
`fix/382-netfx-review-findings` (all already squash-merged as #392, #393
and #385), plus `dependabot-upgrades`. None of them changes any file
against main:
- main already had every bump except TypeScript 7, which
typescript-eslint 8.72 does not support yet (peer range `<6.1.0`);
  - the `lspkit` pin stays on lspkit `main` (`ccc59bf`).

## How Do The Automated Tests Prove It Works?
- **`video-playback.spec.js`**: one test per film, named `<route> video
<n> decodes, pauses, seeks and resumes`. It runs on Chromium, iPhone SE
and iPhone 14 everywhere, and on Windows also on installed `chrome` and
`msedge`. Each film must:
- advance more than 1s and decode more than 5 new frames with `error ===
null`;
  - stay put while paused, so `currentTime` is unchanged after 250ms;
  - advance and decode again after seeking to `duration / 2`.
- **`site-videos.spec.js` › `expectDescribed`** asserts the VideoObject
`contentUrl` is the first listed source.
- **`profiler-media.spec.js`** asserts the hero film's `<source>` order
is MP4 then WebM.
- **The full website Playwright suite (`make _test-website`)** passes
locally, and Deslop reports 6.5% against the 6.65% threshold.

---------

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
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