pxt.ts

/**
 * MakeCode/pxt types needed for the iframe messages.
 *
 * These are substantially derived from the PXT project. The types are hard to use
 * directly due to logical splits that make sense for MakeCode internally, but not
 * for this interface, and TypeScript features that make them hard to reuse in a
 * library context: namespaces and const enums.
 *
 * We've also extracted interfaces for the request parameters separately from the
 * request metadata and corrected some types that don't appear to behave as
 * described.
 *
 * Original is Copyright (c) Microsoft Corporation
 * MIT licensed: https://github.com/microsoft/pxt/blob/master/LICENSE
 *
 * Modifications are Copright (c) Micro:bit Educational Foundation and contributors
 * 2024.
 */

/* eslint-disable @typescript-eslint/no-explicit-any */

export interface InstallHeader {
  name: string; // script name, should always be in sync with pxt.json name
  meta: {
    // json script meta data
    blocksWidth?: number;
    blocksHeight?: number;
    versions?: TargetVersions;
  };
  editor: string; // editor that we're in
  board?: string; // name of the package that contains the board.json info
  temporary?: boolean; // don't serialize project
  // older script might miss this
  target: string;
  // older scripts might miss this
  targetVersion: string;
  pubId: string; // for published scripts
  pubCurrent: boolean; // is this exactly pubId, or just based on it
  pubVersions?: {
    id: string;
    type: 'snapshot' | 'permalink';
  }[];
  pubPermalink?: string; // permanent (persistent) share ID
  anonymousSharePreference?: boolean; // if true, default to sharing anonymously even when logged in
  githubId?: string;
  githubTag?: string; // the release tag if any (commit.tag)
  githubCurrent?: boolean;
  // in progress tutorial if any
  tutorial?: TutorialOptions;
  // completed tutorial info if any
  tutorialCompleted?: {
    // id of the tutorial
    id: string;
    // number of steps completed
    steps: number;
  };
  // workspace guid of the extension under test
  extensionUnderTest?: string;
  // id of cloud user who created this project
  cloudUserId?: string;
  isSkillmapProject?: boolean;
}

export interface Header extends InstallHeader {
  id: string; // guid (generated by us)
  path?: string; // for workspaces that require it
  recentUse: number; // seconds since epoch
  modificationTime: number; // seconds since epoch
  icon?: string; // icon uri

  isDeleted: boolean; // mark whether or not a header has been deleted
  saveId?: any; // used to determine whether a project has been edited while we're saving to cloud

  // For cloud sync (local only metadata)
  cloudVersion: string; // The cloud-assigned version number (e.g. etag)
  cloudCurrent: boolean; // Has the current version of the project been pushed to cloud
  cloudLastSyncTime: number; // seconds since epoch

  // Used for Updating projects
  backupRef?: string; // guid of backed-up project (present if an update was interrupted)
  isBackup?: boolean; // True if this is a backed-up project (for a pending update)

  // Other
  _rev: string; // used for idb / pouchdb revision tracking
}

export type ScriptText = Record<string, string>;

export interface MakeCodeProject {
  header?: Header;
  text?: ScriptText;
}

export interface Asset {
  name: string;
  size: number;
  url: string;
}

export type Version = any;

export interface File {
  header: Header;
  text: ScriptText;
  version: Version;
}

export interface EditorMessage {
  /**
   * Constant identifier
   */
  type: 'pxteditor' | 'pxthost' | 'pxtpkgext' | 'pxtsim';
  /**
   * Original request id
   */
  id?: string;
  /**
   * flag to request response
   */
  response?: boolean;

  /**
   * Frame identifier that can be passed to the iframe by adding the frameId query parameter
   */
  frameId?: string;
}

// In practice some use the `resp` and some use sibling fields.
export interface EditorMessageResponse extends EditorMessage {
  /**
   * Additional response payload provided by the command
   */
  resp?: any;
  /**
   * indicate if operation started or completed successfully
   */
  success: boolean;
  /**
   * Error object if any
   */
  error?: any;
}

export interface EditorMessageRequest extends EditorMessage {
  /**
   * Request action
   */
  action:
    | 'switchblocks'
    | 'switchjavascript'
    | 'switchpython'
    | 'startsimulator'
    | 'restartsimulator'
    | 'stopsimulator' // EditorMessageStopRequest
    | 'hidesimulator'
    | 'showsimulator'
    | 'closeflyout'
    | 'newproject'
    | 'importproject'
    | 'importexternalproject'
    | 'importtutorial'
    | 'openheader'
    | 'proxytosim' // EditorMessageSimulatorMessageProxyRequest
    | 'undo'
    | 'redo'
    | 'renderblocks'
    | 'renderpython'
    | 'renderxml'
    | 'renderbyblockid'
    | 'setscale'
    | 'startactivity'
    | 'saveproject'
    | 'compile'
    | 'unloadproject'
    | 'shareproject'
    | 'savelocalprojectstocloud'
    | 'projectcloudstatus'
    | 'requestprojectcloudstatus'
    | 'convertcloudprojectstolocal'
    | 'setlanguagerestriction'
    | 'gettoolboxcategories'
    | 'toggletrace' // EditorMessageToggleTraceRequest
    | 'showthemepicker'
    | 'togglehighcontrast'
    | 'sethighcontrast' // EditorMessageSetHighContrastRequest
    | 'togglegreenscreen'
    | 'togglekeyboardcontrols'
    | 'settracestate' //
    | 'setsimulatorfullscreen' // EditorMessageSimulatorFullScreenRequest
    | 'print' // print code
    | 'pair' // pair device
    | 'workspacesync' // EditorWorspaceSyncRequest
    | 'workspacereset'
    | 'workspacesave' // EditorWorkspaceSaveRequest
    | 'workspaceloaded'
    | 'workspaceevent' // EditorWorspaceEvent
    | 'workspacediagnostics' // compilation results
    | 'event'
    | 'simevent'
    | 'info' // return info data`
    | 'tutorialevent'
    | 'editorcontentloaded'
    | 'serviceworkerregistered'
    | 'runeval';
}

/**
 * Request sent by the editor when a tick/error/expection is registered
 */
export interface EditorMessageEventRequest extends EditorMessageRequest {
  action: 'event';
  // metric identifier
  tick: string;
  // error category if any
  category?: string;
  // error message if any
  message?: string;
  // custom data
  data?: Record<string, string | number>;
}

export type EditorMessageTutorialEventRequest =
  | EditorMessageTutorialProgressEventRequest
  | EditorMessageTutorialCompletedEventRequest
  | EditorMessageTutorialLoadedEventRequest
  | EditorMessageTutorialExitEventRequest;

export interface EditorMessageTutorialProgressEventRequest
  extends EditorMessageRequest {
  action: 'tutorialevent';
  tutorialEvent: 'progress';
  currentStep: number;
  totalSteps: number;
  isCompleted: boolean;
  tutorialId: string;
  projectHeaderId: string;
}

export interface EditorMessageTutorialCompletedEventRequest
  extends EditorMessageRequest {
  action: 'tutorialevent';
  tutorialEvent: 'completed';
  tutorialId: string;
  projectHeaderId: string;
}

export interface EditorMessageTutorialLoadedEventRequest
  extends EditorMessageRequest {
  action: 'tutorialevent';
  tutorialEvent: 'loaded';
  tutorialId: string;
  projectHeaderId: string;
}

export interface EditorMessageTutorialExitEventRequest
  extends EditorMessageRequest {
  action: 'tutorialevent';
  tutorialEvent: 'exit';
  tutorialId: string;
  projectHeaderId: string;
}

export interface EditorMessageStopRequest extends EditorMessageRequest {
  action: 'stopsimulator';
  /**
   * Indicates if simulator iframes should be unloaded or kept hot.
   */
  unload?: boolean;
}

export interface EditorMessageNewProjectRequest extends EditorMessageRequest {
  action: 'newproject';
  /**
   * Additional optional to create new project
   */
  options?: ProjectCreationOptions;
}

export interface EditorContentLoadedRequest extends EditorMessageRequest {
  action: 'editorcontentloaded';
}

export interface EditorMessageSetScaleRequest extends EditorMessageRequest {
  action: 'setscale';
  scale: number;
}

export interface EditorMessageSimulatorMessageProxyRequest
  extends EditorMessageRequest {
  action: 'proxytosim';
  /**
   * Content to send to the simulator
   */
  content: any;
}

export interface EditorWorkspaceSyncRequest extends EditorMessageRequest {
  /**
   * Synching projects from host into
   */
  action: 'workspacesync' | 'workspacereset' | 'workspaceloaded';
}

export interface EditorWorkspaceEvent extends EditorMessageRequest {
  action: 'workspaceevent';
  event: EditorEvent;
}

export interface EditorWorkspaceDiagnostics extends EditorMessageRequest {
  action: 'workspacediagnostics';
  operation: 'compile' | 'decompile' | 'typecheck';
  output: string;
  diagnostics: {
    code: number;
    category: 'error' | 'warning' | 'message';
    fileName?: string;
    start?: number;
    length?: number;
    line?: number;
    column?: number;
    endLine?: number;
    endColumn?: number;
  }[];
}

// UI properties to sync on load
export interface EditorSyncState {
  // (optional) filtering argument
  filters?: ProjectFilters;
  // (optional) show or hide the search bar
  searchBar?: boolean;
}

export interface EditorWorkspaceSyncResponse extends EditorMessageResponse {
  /*
   * Full list of project, required for init
   */
  projects: MakeCodeProject[];
  // (optional) filtering argument
  editor?: EditorSyncState;
  // (optional) controller id, used for determining what the parent controller is
  controllerId?: string;
}

export interface EditorWorkspaceSaveRequest extends EditorMessageRequest {
  action: 'workspacesave';
  /*
   * Modified project
   */
  project: MakeCodeProject;
}

export interface ImportProjectOptions {
  // project to load
  project: MakeCodeProject;
  // (optional) filtering argument
  filters?: ProjectFilters;
  searchBar?: boolean;
}

export interface EditorMessageImportProjectRequest
  extends EditorMessageRequest,
    ImportProjectOptions {
  action: 'importproject';
}

export interface ImportExternalProjectOptions {
  // project to load
  project: MakeCodeProject;
}

export interface EditorMessageImportExternalProjectRequest
  extends EditorMessageRequest,
    ImportExternalProjectOptions {
  action: 'importexternalproject';
}

export interface EditorMessageImportExternalProjectResponse
  extends EditorMessageResponse {
  action: 'importexternalproject';
  resp: {
    importUrl: string;
  };
}

export interface EditorMessageSaveLocalProjectsToCloud
  extends EditorMessageRequest {
  action: 'savelocalprojectstocloud';
  headerIds: string[];
}

export interface EditorMessageSaveLocalProjectsToCloudResponse
  extends EditorMessageResponse {
  action: 'savelocalprojectstocloud';
  headerIdMap?: Record<string, string>;
}

export interface EditorMessageProjectCloudStatus extends EditorMessageRequest {
  action: 'projectcloudstatus';
  headerId: string;
  status: CloudStatus;
}

export interface EditorMessageRequestProjectCloudStatus
  extends EditorMessageRequest {
  action: 'requestprojectcloudstatus';
  headerIds: string[];
}

export interface EditorMessageConvertCloudProjectsToLocal
  extends EditorMessageRequest {
  action: 'convertcloudprojectstolocal';
  userId: string;
}

export interface EditorMessageImportTutorialRequest
  extends EditorMessageRequest {
  action: 'importtutorial';
  // markdown to load
  markdown: string;
}

export interface EditorMessageOpenHeaderRequest extends EditorMessageRequest {
  action: 'openheader';
  headerId: string;
}

export interface RenderBlocksOptions {
  // typescript code to render
  ts: string;
  // rendering options
  snippetMode?: boolean;
  layout?: BlockLayout;
}

export interface EditorMessageRenderBlocksRequest
  extends EditorMessageRequest,
    RenderBlocksOptions {
  action: 'renderblocks';
}

export interface RenderXmlOptions {
  // xml to render
  xml: string;
  snippetMode?: boolean;
  layout?: BlockLayout;
}

export interface EditorMessageRenderXmlRequest
  extends EditorMessageRequest,
    RenderXmlOptions {
  action: 'renderxml';
}

export interface RenderByBlockIdOptions {
  blockId: string;
  snippetMode?: boolean;
  layout?: BlockLayout;
}

export interface EditorMessageRenderByBlockIdRequest
  extends EditorMessageRequest,
    RenderByBlockIdOptions {
  action: 'renderbyblockid';
}

export interface EditorMessageRenderBlocksResponse {
  // Corrected vs pxt
  resp: string | undefined;
}

export interface EditorMessageRenderXmlResponse {
  // Corrected vs pxt
  resp: string | undefined;
}

export interface EditorMessageRenderByBlockIdResponse {
  // Corrected vs pxt
  resp: string | undefined;
}

export interface EditorMessageRenderPythonRequest extends EditorMessageRequest {
  action: 'renderpython';
  // typescript code to render
  ts: string;
}

export interface EditorMessageRenderPythonResponse {
  // Corrected vs `python` in pxt
  resp: string;
}

export interface EditorSimulatorEvent extends EditorMessageRequest {
  action: 'simevent';
  subtype: 'toplevelfinished' | 'started' | 'stopped' | 'resumed';
}

export interface EditorSimulatorStoppedEvent extends EditorSimulatorEvent {
  subtype: 'stopped';
  exception?: string;
}

export interface EditorMessageToggleTraceRequest extends EditorMessageRequest {
  action: 'toggletrace';
  // interval speed for the execution trace
  intervalSpeed?: number;
}

export interface EditorMessageSetTraceStateRequest
  extends EditorMessageRequest {
  action: 'settracestate';
  enabled: boolean;
  // interval speed for the execution trace
  intervalSpeed?: number;
}

export interface EditorMessageSetSimulatorFullScreenRequest
  extends EditorMessageRequest {
  action: 'setsimulatorfullscreen';
  enabled: boolean;
}

export interface EditorMessageSetHighContrastRequest
  extends EditorMessageRequest {
  action: 'sethighcontrast';
  on: boolean;
}

export interface StartActivityOptions {
  activityType: 'tutorial' | 'example' | 'recipe';
  path: string;
  title?: string;
  previousProjectHeaderId?: string;
  carryoverPreviousCode?: boolean;
}

export interface EditorMessageStartActivity
  extends EditorMessageRequest,
    StartActivityOptions {
  action: 'startactivity';
}

export interface InfoMessage {
  versions: TargetVersions;
  locale: string;
  availableLocales?: string[];
  keyboardControls: boolean;
}

export interface PackageExtensionData {
  ts: string;
  json?: any;
}

export interface EditorPkgExtMessageRequest extends EditorMessageRequest {
  // extension identifier
  package: string;
}

export interface EditorPkgExtMessageResponse extends EditorMessageResponse {
  // extension identifier
  package: string;
}

export interface EditorSimulatorTickEvent extends EditorMessageEventRequest {
  type: 'pxtsim';
}

export interface EditorShareRequest extends EditorMessageRequest {
  action: 'shareproject';
  headerId: string;
  projectName: string;
}

export interface ShareResult {
  embed: {
    code: string;
    editor: string;
    simulator: string;
  };
  qr: string;
  url: string;
}

// Supertype and resp type corrected vs pxt
export interface EditorShareResponse extends EditorMessageResponse {
  action: 'shareproject';
  resp: ShareResult;
}

export interface EditorSetLanguageRestriction extends EditorMessageRequest {
  action: 'setlanguagerestriction';
  restriction: LanguageRestriction;
}

export interface EditorMessageGetToolboxCategoriesRequest
  extends EditorMessageRequest {
  action: 'gettoolboxcategories';
  advanced?: boolean;
}

export interface EditorMessageServiceWorkerRegisteredRequest
  extends EditorMessageRequest {
  action: 'serviceworkerregistered';
}

export interface EditorMessageGetToolboxCategoriesResponse {
  categories: ToolboxCategoryDefinition[];
}

export interface ProjectTemplate {
  id: string;
  config: PackageConfig;
  files: Record<string, string>;
}

export interface ProjectCreationOptions {
  prj?: ProjectTemplate;
  name?: string;
  documentation?: string;
  filesOverride?: Record<string, string>;
  filters?: ProjectFilters;
  temporary?: boolean;
  tutorial?: TutorialOptions;
  dependencies?: Record<string, string>;
  tsOnly?: boolean; // DEPRECATED: use LanguageRestriction.NoBlocks or LanguageRestriction.JavaScriptOnly instead
  languageRestriction?: LanguageRestriction;
  preferredEditor?: string; // preferred editor to open, pxt.BLOCKS_PROJECT_NAME, ...
  extensionUnderTest?: string; // workspace id of the extension under test
  skillmapProject?: boolean;
  simTheme?: Partial<PackageConfig>;
  firstProject?: boolean;
}

export interface ProjectFilters {
  namespaces?: { [index: string]: FilterState };
  blocks?: { [index: string]: FilterState };
  fns?: { [index: string]: FilterState };
  defaultState?: FilterState;
}

export enum FilterState {
  Hidden = 0,
  Visible = 1,
  Disabled = 2,
}

export enum BlockLayout {
  None = 0,
  Align = 1,
  // Shuffle deprecated
  Clean = 3,
  Flow = 4,
}

export type EditorType = 'blocks' | 'ts';

// Switched from supertype to discriminated union
export type EditorEvent = CreateEvent | UIEvent;

export interface CreateEvent {
  type: 'create';
  blockId: string;
}

export interface UIEvent {
  type: 'ui';
  action: 'groupHelpClicked';
  data?: Record<string, string>;
}

export interface NativeHostMessage {
  name?: string;
  download?: string;
  save?: string;
  cmd?: string;
}

// This is defined with the sim types and copied in here

export interface ImportFileOptions {
  filename: string;
  parts: (string | ArrayBuffer)[];
}

// This is defined in pxtarget.d.ts as a const enum but is on our interface
export type LanguageRestriction =
  | /* Standard */ ''
  | 'python-only'
  | 'javascript-only'
  | 'blocks-only'
  | 'no-blocks'
  | 'no-python'
  | 'no-javascript';

export interface ToolboxCategoryDefinition {
  /**
   * The display name for the category
   */
  name?: string;

  /**
   * The icon of this category
   */
  icon?: string;

  /**
   * The color of this category
   */
  color?: string;

  /**
   * The weight of the category relative to other categories in the toolbox
   */
  weight?: number;

  /**
   * Whether or not the category should be placed in the advanced category
   */
  advanced?: boolean;

  /**
   * Blocks to appear in the category. Specifying this field will override
   * all existing blocks in the category. The ordering of the blocks is
   * determined by the ordering of this array.
   */
  blocks?: ToolboxBlockDefinition[];

  /**
   * Ordering of category groups
   */
  groups?: string[];
}

export interface ToolboxBlockDefinition {
  /**
   * Internal id used to refer to this block or snippet, must be unique
   */
  name: string;

  /**
   * Group label used to categorize block.  Blocks are arranged with other
   * blocks that share the same group.
   */
  group?: string;

  /**
   * Indicates an advanced API. Advanced APIs appear after basic ones in the
   * toolbox
   */
  advanced?: boolean;

  /**
   * The weight for the block. Blocks are arranged in order of they appear in the category
   * definition's array but the weight can be specified in the case that other APIs are
   * dynamically added to the category (eg. loops.forever())
   */
  weight?: number;

  /**
   * Description of code to appear in the hover text
   */
  jsDoc?: string;

  /**
   * TypeScript snippet of code to insert when dragged into editor
   */
  snippet?: string;

  /**
   * Python snippet of code to insert when dragged into editor
   */
  pySnippet?: string;

  /**
   * TypeScript name used for highlighting the snippet, uses name if not defined
   */
  snippetName?: string;

  /**
   * Python name used for highlighting the snippet, uses name if not defined
   */
  pySnippetName?: string;

  /**
   * Display just the snippet and nothing else. Should be set to true for
   * language constructs (eg. for-loops) and to false for function
   * calls (eg. Math.random())
   */
  snippetOnly?: boolean;

  /**
   * The return type of the block. This is used to determine the shape of the block rendered.
   */
  retType?: string;

  /**
   * The block definition in XML for the blockly toolbox.
   */
  blockXml?: string;

  /**
   * The Blockly block id used to identify this block.
   */
  blockId?: string;
}

export type CloudStatus =
  | 'none'
  | 'synced'
  | 'justSynced'
  | 'offline'
  | 'syncing'
  | 'conflict'
  | 'localEdits';

export type CodeCardType =
  | 'file'
  | 'example'
  | 'codeExample'
  | 'tutorial'
  | 'side'
  | 'template'
  | 'package'
  | 'hw'
  | 'forumUrl'
  | 'forumExample'
  | 'sharedExample'
  | 'link';
export type CodeCardEditorType = 'blocks' | 'js' | 'py';

export interface DependencyMap<T> {
  [index: string]: T;
}

export interface TargetVersions {
  target: string;
  targetId?: string;
  targetWebsite?: string;
  pxt?: string;
  tag?: string;
  branch?: string;
  commits?: string; // URL
}

export interface CodeCardAction {
  url: string;
  editor?: CodeCardEditorType;
  cardType?: CodeCardType;
}

/**
 * The schema for the pxt.json package files
 */
export interface PackageConfig {
  name: string;
  version?: string;
  // installedVersion?: string; moved to Package class
  // url to icon -- support for built-in packages only
  icon?: string;
  // semver description for support target version
  documentation?: string; // doc page to open when loading project, used by sidedocs
  targetVersions?: TargetVersions; // versions of the target/pxt the package was compiled against
  description?: string;
  dependencies: DependencyMap<string>;
  license?: string;
  authors?: string[];
  files: string[];
  simFiles?: string[];
  testFiles?: string[];
  fileDependencies?: DependencyMap<string>; // exclude certain files if dependencies are not fulfilled
  preferredEditor?: string; // tsprj, blocksprj, pyprj
  languageRestriction?: LanguageRestriction; // language restrictions that have been placed on the package
  testDependencies?: Record<string, string>;
  cppDependencies?: Record<string, string>;
  public?: boolean;
  partial?: boolean; // true if project is not compileable on its own (eg base)
  binaryonly?: boolean;
  platformio?: {
    dependencies?: DependencyMap<string>;
  };
  compileServiceVariant?: string;
  palette?: string[];
  paletteNames?: string[];
  screenSize?: {
    width: number;
    height: number;
  };
  yotta?: YottaConfig;
  codal?: {
    libraries?: string[];
  };
  npmDependencies?: DependencyMap<string>;
  card?: CodeCard;
  additionalFilePath?: string;
  additionalFilePaths?: string[];
  core?: boolean;
  // used for sorting for core packages
  weight?: number;
  gistId?: string;
  extension?: PackageExtension; // describe the associated extension if any
  isExtension?: boolean; // is this package an extension
  dalDTS?: {
    corePackage?: string;
    includeDirs?: string[];
    excludePrefix?: string[];
    compileServiceVariant?: string;
  };
  features?: string[];
  hidden?: boolean; // hide package from package selection dialog
  searchOnly?: boolean; // do not show by default, only as search result
  skipLocalization?: boolean;
  snippetBuilders?: SnippetConfig[];
  experimentalHw?: boolean;
  requiredCategories?: string[]; // ensure that those block categories are visible
  supportedTargets?: string[]; // a hint about targets in which this extension is supported
  firmwareUrl?: string; // link to documentation page about upgrading firmware
  disablesVariants?: string[]; // don't build these variants, when this extension is enabled
  utf8?: boolean; // force compilation with UTF8 enabled
  disableTargetTemplateFiles?: boolean; // do not override target template files when commiting to github
  theme?: string | Record<string, string>;
  assetPack?: boolean; // if set to true, only the assets of this project will be imported when added as an extension (no code)
  assetPacks?: DependencyMap<boolean>; // a map of dependency id to boolean that indicates which dependencies should be imported as asset packs
}

export interface PackageExtension {
  // Namespace to add the button under, defaults to package name
  namespace?: string;
  // Group to place button in
  group?: string;
  // Label for the flyout button, defaults to `Editor`
  label?: string;
  // for new category, category color
  color?: string;
  // for new category, is category advanced
  advanced?: boolean;
  // trusted custom editor url, must be register in targetconfig.json under approvedEditorExtensionUrls
  url?: string;
  // local debugging URL used when served through pxt serve and debugExtensions=1 mode
  localUrl?: string;
}

export interface YottaConfig {
  dependencies?: DependencyMap<string>;
  config?: any;
  /**
   * Overridable config flags
   */
  optionalConfig?: any;
  userConfigs?: {
    description: string;
    config: any;
  }[];
  /* deprecated */
  configIsJustDefaults?: boolean;
  /* deprecated */
  ignoreConflicts?: boolean;
}

export interface CodeCard {
  name?: string;
  shortName?: string;
  title?: string;
  role?: string;
  ariaLabel?: string;
  label?: string;
  labelIcon?: string;
  labelClass?: string;
  tags?: string[]; // tags shown in home screen, colors specified in theme
  tabIndex?: number;
  style?: string; // "card" | "item" | undefined;

  color?: string; // one of semantic ui colors
  description?: string;
  extracontent?: string;
  blocksXml?: string;
  typeScript?: string;
  imageUrl?: string;
  largeImageUrl?: string;
  videoUrl?: string;
  youTubeId?: string;
  youTubePlaylistId?: string; // playlist this video belongs to
  buttonLabel?: string;
  actionIcon?: string; // icon to override default icon on the action button
  time?: number;
  url?: string;
  learnMoreUrl?: string;
  buyUrl?: string;
  feedbackUrl?: string;
  responsive?: boolean;
  cardType?: CodeCardType;
  editor?: CodeCardEditorType;
  otherActions?: CodeCardAction[];
  directOpen?: boolean; // skip the details view, directly do the card action
  projectId?: string; // the project's header ID

  header?: string;

  tutorialStep?: number;
  tutorialLength?: number;

  icon?: string;
  iconContent?: string; // Text instead of icon name
  iconColor?: string;

  onClick?: (e: any) => void; // React event
  onLabelClicked?: (e: any) => void;

  target?: string;
  className?: string;
  variant?: string;
}
export interface SnippetConfig {
  name: string;
  namespace: string;
  group?: string;
  label: string;
  outputType: 'blocks';
  outputBehavior?: /*assumed default*/ 'merge' | 'replace';
  initialOutput?: string;
  questions: SnippetQuestions[];
}

export type SnippetAnswerTypes =
  | 'number'
  | 'text'
  | 'variableName'
  | 'dropdown'
  | 'spriteEditor'
  | 'yesno'
  | string; // TODO(jb) Should include custom answer types for number, enums, string, image

export interface SnippetGoToOptions {
  question?: number;
  validate?: {
    regex?: {
      token: string;
      regex: string;
      match?: SnippetParameters;
      noMatch?: SnippetParameters;
    };
  };
  parameters?: SnippetParameters[]; // Answer token with corresponding question
}

export interface SnippetParameters {
  token?: string;
  answer?: string;
  question: number;
}

export type SnippetQuestionInput = { label?: string } & (
  | {
      // Singular input answer.
      answerToken: string;
      defaultAnswer: SnippetAnswerTypes;
    }
  | {
      // Plural input answer.
      answerTokens: string[];
      defaultAnswers: SnippetAnswerTypes[];
    }
) &
  (
    | {
        type: string;
      }
    | {
        type: 'number' | 'positionPicker';
        max?: number;
        min?: number;
      }
    | {
        type: 'dropdown';
        options: Record<string, string>;
      }
    | {
        type: 'yesno';
      }
  );

export interface SnippetQuestions {
  title: string;
  output?: string;
  outputConditionalOnAnswer?: string;
  errorMessage?: string;
  goto?: SnippetGoToOptions;
  inputs: SnippetQuestionInput[];
  hint?: string;
}

export interface TutorialOptions {
  tutorial?: string; // tutorial
  tutorialName?: string; // tutorial title
  tutorialReportId?: string; // if this tutorial was user generated, the report abuse id
  tutorialStepInfo?: TutorialStepInfo[];
  tutorialActivityInfo?: TutorialActivityInfo[];
  tutorialStep?: number; // current tutorial page
  tutorialReady?: boolean; // current tutorial page
  tutorialHintCounter?: number; // count for number of times hint has been shown
  tutorialStepExpanded?: boolean; // display full step in dialog
  tutorialMd?: string; // full tutorial markdown
  tutorialCode?: string[]; // all tutorial code bundled
  tutorialRecipe?: boolean; // micro tutorial running within the context of a script
  templateCode?: string;
  mergeHeaderId?: string;
  mergeCarryoverCode?: boolean;
  autoexpandStep?: boolean; // autoexpand tutorial card if instruction text overflows
  metadata?: TutorialMetadata; // metadata about the tutorial parsed from the markdown
  language?: string; // native language of snippets ("python" for python, otherwise defaults to typescript)
  assetFiles?: Record<string, string>;
  jres?: string; // JRES to be used when generating hints; necessary for tilemaps
  customTs?: string; // custom typescript code loaded in a separate file for the tutorial
  templateLoaded?: boolean; // if the template code has been loaded once, we skip
  globalBlockConfig?: TutorialBlockConfig; // concatenated `blockconfig.global` sections. Contains block configs applicable to all tutorial steps
  globalValidationConfig?: CodeValidationConfig; // concatenated 'validation.global' sections. Contains validation config applicable to all steps
  simTheme?: Partial<PackageConfig>;
}

export interface TutorialStepInfo {
  // Step metadata
  showHint?: boolean; // automatically displays hint
  showDialog?: boolean; // no coding, displays in modal
  resetDiff?: boolean; // reset diffify algo
  tutorialCompleted?: boolean;

  // Step content
  title?: string;
  activity?: number;
  contentMd?: string;

  // Old
  headerContentMd?: string;
  hintContentMd?: string;
  // fullscreen?: boolean; // DEPRECATED, replaced by "showHint"
  // unplugged?: boolean: // DEPRECATED, replaced by "showDialog"

  // concatenated `blockconfig.local` sections. Contains block configs applicable to the current step only
  localBlockConfig?: TutorialBlockConfig;

  // concatenated 'validation.local' sections. Contains config applicable to this step only.
  localValidationConfig?: CodeValidationConfig;
}

export interface TutorialBlockConfig {
  md?: string; // `blockconfig` markdown fragment
  blocks?: {
    blockId?: string;
    xml?: string;
  }[]; // markdown fragment can contain multiple block definitions
}

export interface TutorialMetadata {
  activities?: boolean; // tutorial consists of activities, then steps. uses `###` for steps
  explicitHints?: boolean; // tutorial expects explicit hints in `#### ~ tutorialhint` format
  flyoutOnly?: boolean; // no categories, display all blocks in flyout
  hideIteration?: boolean; // hide step control in tutorial
  diffs?: boolean; // automatically diff snippets
  noDiffs?: boolean; // don't automatically generated diffs
  codeStart?: string; // command to run when code starts (MINECRAFT HOC ONLY)
  codeStop?: string; // command to run when code stops (MINECRAFT HOC ONLY)
  autoexpandOff?: boolean; // INTERNAL TESTING ONLY
  preferredEditor?: string; // preferred editor for opening the tutorial
}

export interface TutorialActivityInfo {
  name: string;
  step: number;
}

export interface CodeValidationConfig {
  validatorsMetadata: {
    validatorType: string;
    properties: {
      enabled?: string;
      markers?: string;
    };
  }[];
}