Walkthroughs

Onboarding content. A walkthrough is a sequence of steps the host presents to someone who has not used your mod yet.

import { function defineMod<const TMod extends ModDefinition>(definition: TMod & ValidateModHooks<TMod>): Mod
The entry point of the SDK. A mod's module default-exports one `defineMod`
call and nothing else.

The returned value is data. It registers nothing, starts nothing, and
touches no host state. The host folds it twice. At build time it runs the
module in a throwaway sandbox and reads the value to derive the serializable
manifest. At runtime it folds the same value again to wire your handlers
into their lanes: ext-host for commands, tools, effects, and hooks; the
sandboxed renderer for views and widgets.

That double fold is why the module must be pure. It is re-executed to
produce the manifest, so anything at the top level, a file read, a network
call, a timer, a `console` line, runs during a build with no host attached.
Put behavior inside handlers: `run`, `activate`, `handle`.

The `ValidateModHooks` constraint makes the call fail to typecheck when a
`hook.beforeAction` targets an action that is neither a known host action
nor `command:` plus one of this mod's own command ids.
@example```ts
export default defineMod({
  metadata: {
    displayName: 'Review',
    description: 'Review helpers for the current change.',
  },
  commands: [
    command({ id: 'review.open', title: 'Review: Open', run: openPanel }),
    slashCommand({ id: 'review', description: 'Review this change', run: review }),
  ],
  ai: {
    tools: [reviewTool],
  },
});
```@categoryAuthoringdefineMod, function walkthrough<TId extends string>(walkthroughValue: WalkthroughInput<TId>): Walkthrough<TId>
Declare a guided set of onboarding steps the host presents.

Declarative, like `theme`: no handler, no code path of yours runs. Each step
carries its own copy and media, and marks itself done either when a named
command runs or when one of its completion events fires, so the host tracks
progress without the mod polling anything.

This is for teaching a mod, one screen at a time. To put UI in front of the
user on demand, use `view` or `widget` instead.
@categoryAuthoringwalkthrough } from '@modular/sdk';

export default 
defineMod<{
    readonly metadata: {
        readonly displayName: "Panels";
        readonly description: "Contributed surfaces";
    };
    readonly walkthroughs: readonly [Walkthrough<string>];
}>(definition: {
    readonly metadata: {
        readonly displayName: "Panels";
        readonly description: "Contributed surfaces";
    };
    readonly walkthroughs: readonly [Walkthrough<string>];
}): Mod
The entry point of the SDK. A mod's module default-exports one `defineMod`
call and nothing else.

The returned value is data. It registers nothing, starts nothing, and
touches no host state. The host folds it twice. At build time it runs the
module in a throwaway sandbox and reads the value to derive the serializable
manifest. At runtime it folds the same value again to wire your handlers
into their lanes: ext-host for commands, tools, effects, and hooks; the
sandboxed renderer for views and widgets.

That double fold is why the module must be pure. It is re-executed to
produce the manifest, so anything at the top level, a file read, a network
call, a timer, a `console` line, runs during a build with no host attached.
Put behavior inside handlers: `run`, `activate`, `handle`.

The `ValidateModHooks` constraint makes the call fail to typecheck when a
`hook.beforeAction` targets an action that is neither a known host action
nor `command:` plus one of this mod's own command ids.
@example```ts
export default defineMod({
  metadata: {
    displayName: 'Review',
    description: 'Review helpers for the current change.',
  },
  commands: [
    command({ id: 'review.open', title: 'Review: Open', run: openPanel }),
    slashCommand({ id: 'review', description: 'Review this change', run: review }),
  ],
  ai: {
    tools: [reviewTool],
  },
});
```@categoryAuthoringdefineMod({
  
metadata: {
    readonly displayName: "Panels";
    readonly description: "Contributed surfaces";
}metadata: { displayName: "Panels"displayName: 'Panels', description: "Contributed surfaces"description: 'Contributed surfaces' },
  walkthroughs: readonly [Walkthrough<string>]walkthroughs: [
    walkthrough<string>(walkthroughValue: WalkthroughInput<string>): Walkthrough<string>
Declare a guided set of onboarding steps the host presents.

Declarative, like `theme`: no handler, no code path of yours runs. Each step
carries its own copy and media, and marks itself done either when a named
command runs or when one of its completion events fires, so the host tracks
progress without the mod polling anything.

This is for teaching a mod, one screen at a time. To put UI in front of the
user on demand, use `view` or `widget` instead.
@categoryAuthoringwalkthrough({
      Walkthrough<string>.id: stringid: 'panels.getting-started',
      Walkthrough<TId extends string = string>.title: stringtitle: 'Getting started',
      Walkthrough<TId extends string = string>.description: stringdescription: 'Open your first panel.',
      Walkthrough<TId extends string = string>.steps: readonly WalkthroughStep<string>[]steps: [
        {
          WalkthroughStep<string>.id: stringid: 'open-outline',
          WalkthroughStep<string>.title: stringtitle: 'Open the outline',
          WalkthroughStep<string>.media: WalkthroughMediamedia: { markdown: stringmarkdown: 'Press the outline icon in the right sidebar.' },
          
WalkthroughStep<string>.doneOn?: {
    readonly command: string;
} | undefineddoneOn: { command: stringcommand: 'panels.outline.open' },
        },
      ],
    }),
  ],
});

media is a union with never on every sibling branch, so a step carries an image, markdown, an svg, or a video — never two at once.

Members

Walkthrough — id, title, description, icon, steps, featuredFor, when.

featuredFor is the member that makes a walkthrough worth writing. It is what surfaces the walkthrough to the right person at the right moment, rather than leaving it in a list nobody opens.

when gates it entirely — use it to stop showing a walkthrough to someone who has already finished the thing it teaches.

Not a surface you control

Unlike a view or a widget, you do not render a walkthrough. You describe its steps and the host draws them, so it matches the rest of the onboarding a person sees.