Cursorless tutorial units 1 & 2

[pokey]

Todo

• Install locally and try everything out
• Try "cursorless docs" both inside and outside of VSCode
• I have not broken the cheatsheet
• Make it more obvious that the tutorial list is a list of all tutorials
• Change what we show when tutorial prereqs no longer met, eg "prereqs not met, feel free to keep playing, and say resume to resume"
• Add note at end of unit 1 suggesting they continue to play with the document
• Tune tutorial content. Move / add docs tip to end of first tutorial. More stuff maybe better for follow-up PR
• Point out that we're using highlights for marks in first tutorial step
• Have "tutorial exit" command and corresponding button
• Add paragraph break between sentences in step
• Workshop the actual text in the editor itself so that it indicates they should look at the side bar
• Make color of commands stand out more
• Properly support custom actions and other necessary custom spoken forms
• Store current progress in local storage (and sync it)
• Properly support custom symbol spoken forms (eg alphabet)
• Add "tutorial restart"
• I have added tests
• Fix scope tree view
• How to handle disabled hat color?
• Figure out unicode for emoji
• Figure out what "cursorless tutorial" should actually do. Currently starts second tutorial, which is obv not what we want
• Figure out how to advance from last step of initial tutorial, as it has no action to perform
• Add "tutorial next" / "tutorial previous" commands
• Add tutorial step saying to use "cursorless help" cheatsheat
• Fix broken references to css eg reset
• Invalidate state if custom spoken forms change
• Change view when we detect that prereqs are no longer met (eg cursor in wrong place, etc). Indicate they should say "tutorial continue" / "tutorial restore" / "cursorless tutorial" to reset the prereqs
• Merge HUD changes
• Figure out how to properly detect VSCode focused
• Highlight marks that need to be targeted, so user doesn't have to search for them
• Remove print statements and commented out code from tutorial.py
• Figure out how to only run step preparation when you have the right window focused. Some of the time @pokey gets error message after "cursorles help" step
  
• Open new window on start?
• Ensure you're in the right window / editor before restoring state, so we don't accidentally clobber something
• Get it to work with mainline Talon HUD
• Finish constructing spoken forms from commands
• Use app name for VSCode that works cross-platform
• Figure out what todo with the fact that the cheatsheet clobbers the entire screen and you can't even see the close button (Reimplement cheatsheet using html #619)

See also cursorless-dev/cursorless-talon#143

Unit 2

• Python
• Have an action class?

To cover:

• New scope types
• New actions, including
  • single argument "bring"
  • multiple argument "bring"
  • "move"
  • "swap"
• Simple inference in the context of multiple target actions such as swap or bring

Extra unit

• Probably want to move this into a new pull request
• Create a json script for it
• Don't forget to add the intermediate steps where it was not a cursorless command and so isn't recorded

Links

Helpful places in our code base

• https://github.com/cursorless-dev/cursorless/blob/main/packages/cursorless-vscode-e2e/src/suite/recorded.vscode.test.ts sets up file to initial state of tutorial step
• to generate a spoken form from the command payload in the yaml:

  cursorless/packages/cursorless-engine/src/scopeProviders/ScopeInfoProvider.ts

  Line 95 in a9cc79f

  this.customSpokenFormGenerator.scopeTypeToSpokenForm(scopeType),

• this is where you'll send a command to cursorless requesting it to set up initial tutorial step state and have it return generated spoken form: https://github.com/cursorless-dev/cursorless/pull/360/files#diff-5c1cd9d422f7c8df0325fd0958446c90873fb338c462287ef5f57606a363658bR35-R37
• registering a new command extension-side

  cursorless/packages/cursorless-vscode/src/extension.ts

  Line 125 in a9cc79f

  registerCommands(

In case we decided to look into VSCode walkthroughs rather than Talon hud

• https://code.visualstudio.com/api/references/contribution-points#contributes.walkthroughs

[pokey]

Closing until this becomes an active priority again

[pokey]

Okay this one is a quite large. I must admit I'm not a big fan of how much changes you need to do to the engine. The concept of "lean engine" is thoroughly trampled upon here :D I assume there are good reason why you couldn't do more of this in the composition route for vscode and that just shows that we need a much better plugin based system for the engine. I'm not against merging this, but I think we as soon as possible should try to move things out of the engine.

Note I haven't really had time to test it myself so that is left to do. This was just a first review of the code.

I'm not opposed to moving this into its own package, but I wouldn't want it in vscode as it's generic. Shall I move it into a tutorial package?

[AndreasArvidsson]

Okay this one is a quite large. I must admit I'm not a big fan of how much changes you need to do to the engine. The concept of "lean engine" is thoroughly trampled upon here :D I assume there are good reason why you couldn't do more of this in the composition route for vscode and that just shows that we need a much better plugin based system for the engine. I'm not against merging this, but I think we as soon as possible should try to move things out of the engine.
Note I haven't really had time to test it myself so that is left to do. This was just a first review of the code.

I'm not opposed to moving this into its own package, but I wouldn't want it in vscode as it's generic. Shall I move it into a tutorial package?

Please do!

[pokey]

ok @AndreasArvidsson this is ready for another review and local test. Don't merge yet as I'm going to install it locally and give it one more whirl before shipping

[pokey]

ok I installed locally and it's working well. Give it a try for yourself and if you're happy merge away!

[AndreasArvidsson]

Works really well. Excellent work! :)

• there is no information on how to go back to the previous step. tutorial previous is missing from ui.
• Is there a way to get a progress counter as well as the progress bar?
• say "take harp past drum" made my brain actually say say and just typed out the command :D
• I think I remembered a discussion about the highlights going away when the tutorial was in a incorrect state? I assume you reverted that because it isn't active now
• unit 1 I'm not sure if that is the right way to label the different tutorials. "tutorial 1" is probably better?
• detent this would probably be more memorable on a line with actual text on it?

[pokey]

Works really well. Excellent work! :)

thanks :)

• say "take harp past drum" made my brain actually say say and just typed out the command :D

Should I do something about this or is this just an anecdote? 😄

• dedent this would probably be more memorable on a line with actual text on it?

Not sure I agree. How strongly do you feel?

All other feedback addressed. If you're happy, let's merge!