@tutorialkit-rb/runtime 1.5.2-rb.0.1.0

package/README.md

@@ -0,0 +1,18 @@
+# @tutorialkit/runtime
+
+A wrapper around the **[WebContainer API][webcontainer-api]** focused on providing the right abstractions to let you focus on building highly interactive tutorials.
+
+The runtime exposes the following:
+
+- `TutorialStore`: A store to manage your tutorial content in WebContainer and in your components.
+
+Only a single instance of `TutorialStore` should be created in your application and its lifetime is bound by the lifetime of the WebContainer instance.
+
+## License
+
+MIT
+
+Copyright (c) 2024–present [StackBlitz][stackblitz]
+
+[stackblitz]: https://stackblitz.com/
+[webcontainer-api]: https://webcontainers.io

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Command, Commands, PreviewInfo, Step, Steps } from './webcontainer/index.js';
+export { safeBoot } from './webcontainer/index.js';
+export { TutorialStore } from './store/index.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { safeBoot } from './webcontainer/index.js';
+export { TutorialStore } from './store/index.js';

package/dist/lesson-files.d.ts

@@ -0,0 +1,22 @@
+import type { Files, Lesson } from '@tutorialkit-rb/types';
+type InvalidationResult = {
+    type: 'template' | 'files' | 'solution';
+    files: Files;
+} | {
+    type: 'none';
+};
+export declare class LessonFilesFetcher {
+    private _basePathname;
+    private _map;
+    private _templateLoadTask?;
+    private _templateLoaded;
+    constructor(_basePathname?: string);
+    invalidate(filesRef: string): Promise<InvalidationResult>;
+    getLessonTemplate(lesson: Lesson): Promise<Files>;
+    getLessonFiles(lesson: Lesson): Promise<Files>;
+    getLessonSolution(lesson: Lesson): Promise<Files>;
+    private _fetchTemplate;
+    private _getFilesFromFilesRefList;
+    private _fetchFiles;
+}
+export {};

package/dist/lesson-files.js

@@ -0,0 +1,126 @@
+import { newTask } from './tasks.js';
+import { wait } from './utils/promises.js';
+export class LessonFilesFetcher {
+    _basePathname;
+    _map = new Map();
+    _templateLoadTask;
+    _templateLoaded;
+    constructor(_basePathname = '/') {
+        this._basePathname = _basePathname;
+        if (!this._basePathname.endsWith('/')) {
+            this._basePathname = this._basePathname + '/';
+        }
+    }
+    async invalidate(filesRef) {
+        if (!this._map.has(filesRef)) {
+            return { type: 'none' };
+        }
+        const type = getTypeFromFilesRef(filesRef);
+        let files;
+        if (this._templateLoaded === filesRef) {
+            files = await this._fetchTemplate(filesRef).promise;
+        }
+        else {
+            files = await this._fetchFiles(filesRef);
+        }
+        return {
+            type,
+            files,
+        };
+    }
+    async getLessonTemplate(lesson) {
+        const templatePathname = `template-${lesson.data.template}.json`;
+        if (this._map.has(templatePathname)) {
+            return this._map.get(templatePathname);
+        }
+        if (this._templateLoadTask && this._templateLoaded === templatePathname) {
+            return this._templateLoadTask.promise;
+        }
+        const task = this._fetchTemplate(templatePathname);
+        return task.promise;
+    }
+    getLessonFiles(lesson) {
+        return this._getFilesFromFilesRefList(lesson.files);
+    }
+    getLessonSolution(lesson) {
+        return this._getFilesFromFilesRefList(lesson.solution);
+    }
+    _fetchTemplate(templatePathname) {
+        this._templateLoadTask?.cancel();
+        const task = newTask(async (signal) => {
+            const response = await fetch(`${this._basePathname}${templatePathname}`, { signal });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch: status ${response.status}`);
+            }
+            const body = convertToFiles(await response.json());
+            this._map.set(templatePathname, body);
+            signal.throwIfAborted();
+            return body;
+        });
+        this._templateLoadTask = task;
+        this._templateLoaded = templatePathname;
+        return task;
+    }
+    async _getFilesFromFilesRefList(filesRefList) {
+        // the ref does not have any content
+        if (filesRefList[1].length === 0) {
+            return {};
+        }
+        const pathname = filesRefList[0];
+        if (this._map.has(pathname)) {
+            return this._map.get(pathname);
+        }
+        const promise = this._fetchFiles(pathname);
+        return promise;
+    }
+    async _fetchFiles(pathname) {
+        let retry = 2;
+        while (true) {
+            try {
+                const response = await fetch(`${this._basePathname}${pathname}`);
+                if (!response.ok) {
+                    throw new Error(`Failed to fetch ${pathname}: ${response.status} ${response.statusText}`);
+                }
+                const body = convertToFiles(await response.json());
+                this._map.set(pathname, body);
+                return body;
+            }
+            catch (error) {
+                if (retry <= 0) {
+                    console.error(`Failed to fetch ${pathname} after 3 attempts.`);
+                    console.error(error);
+                    return {};
+                }
+            }
+            retry -= 1;
+            await wait(1000);
+        }
+    }
+}
+function convertToFiles(json) {
+    const result = {};
+    if (typeof json !== 'object') {
+        return result;
+    }
+    for (const property in json) {
+        const value = json[property];
+        let transformedValue;
+        if (typeof value === 'object') {
+            transformedValue = Uint8Array.from(atob(value.base64), (char) => char.charCodeAt(0));
+        }
+        else {
+            transformedValue = value;
+        }
+        result[property] = transformedValue;
+    }
+    return result;
+}
+function getTypeFromFilesRef(filesRef) {
+    if (filesRef.startsWith('template-')) {
+        return 'template';
+    }
+    if (filesRef.endsWith('files.json')) {
+        return 'files';
+    }
+    return 'solution';
+}

package/dist/store/editor.d.ts

@@ -0,0 +1,29 @@
+import type { FilesRefList, Files, EditorSchema, FileDescriptor } from '@tutorialkit-rb/types';
+import { EditorConfig } from '../webcontainer/editor-config.js';
+export interface EditorDocument {
+    value: string | Uint8Array;
+    loading: boolean;
+    filePath: string;
+    type: FileDescriptor['type'];
+    scroll?: ScrollPosition;
+}
+export interface ScrollPosition {
+    top: number;
+    left: number;
+}
+export type EditorDocuments = Record<string, EditorDocument | undefined>;
+export declare class EditorStore {
+    editorConfig: import("nanostores").WritableAtom<EditorConfig>;
+    selectedFile: import("nanostores").WritableAtom<string | undefined>;
+    documents: import("nanostores").MapStore<EditorDocuments>;
+    files: import("nanostores").ReadableAtom<FileDescriptor[]>;
+    currentDocument: import("nanostores").ReadableAtom<EditorDocument | undefined>;
+    setEditorConfig(config?: EditorSchema): void;
+    setSelectedFile(filePath: string | undefined): void;
+    setDocuments(files: FilesRefList | Files): void;
+    updateScrollPosition(filePath: string, position: ScrollPosition): void;
+    addFileOrFolder(file: FileDescriptor): void;
+    updateFile(filePath: string, content: string | Uint8Array): boolean;
+    deleteFile(filePath: string): boolean;
+    onDocumentChanged(filePath: string, callback: (document: Readonly<EditorDocument>) => void): () => void;
+}

package/dist/store/editor.js

@@ -0,0 +1,127 @@
+import { atom, map, computed } from 'nanostores';
+import { EditorConfig } from '../webcontainer/editor-config.js';
+export class EditorStore {
+    editorConfig = atom(new EditorConfig());
+    selectedFile = atom();
+    documents = map({});
+    files = computed(this.documents, (documents) => Object.entries(documents).map(([path, doc]) => ({ path, type: doc?.type || 'file' })));
+    currentDocument = computed([this.documents, this.selectedFile], (documents, selectedFile) => {
+        if (!selectedFile) {
+            return undefined;
+        }
+        return documents[selectedFile];
+    });
+    setEditorConfig(config) {
+        this.editorConfig.set(new EditorConfig(config));
+    }
+    setSelectedFile(filePath) {
+        this.selectedFile.set(filePath);
+    }
+    setDocuments(files) {
+        // lesson, solution and template file entries are always files  - empty folders are not supported
+        const type = 'file';
+        // check if it is a FilesRef
+        if (Array.isArray(files)) {
+            this.documents.set(Object.fromEntries(files[1].map((filePath) => {
+                return [
+                    filePath,
+                    {
+                        value: '',
+                        type,
+                        loading: true,
+                        filePath,
+                    },
+                ];
+            })));
+        }
+        else {
+            const previousDocuments = this.documents.value;
+            this.documents.set(Object.fromEntries(Object.entries(files).map(([filePath, value]) => {
+                return [
+                    filePath,
+                    {
+                        value,
+                        type,
+                        loading: false,
+                        filePath,
+                        scroll: previousDocuments?.[filePath]?.scroll,
+                    },
+                ];
+            })));
+        }
+    }
+    updateScrollPosition(filePath, position) {
+        const documentState = this.documents.get()[filePath];
+        if (!documentState) {
+            return;
+        }
+        this.documents.setKey(filePath, {
+            ...documentState,
+            scroll: position,
+        });
+    }
+    addFileOrFolder(file) {
+        // when adding file or folder to empty folder, remove the empty folder from documents
+        const emptyFolder = this.files.get().find((f) => file.path.startsWith(f.path));
+        if (emptyFolder) {
+            this.documents.setKey(emptyFolder.path, undefined);
+        }
+        this.documents.setKey(file.path, {
+            filePath: file.path,
+            type: file.type,
+            value: '',
+            loading: false,
+        });
+    }
+    updateFile(filePath, content) {
+        const documentState = this.documents.get()[filePath];
+        if (!documentState) {
+            return false;
+        }
+        const currentContent = documentState.value;
+        const contentChanged = currentContent !== content;
+        if (contentChanged) {
+            this.documents.setKey(filePath, {
+                ...documentState,
+                value: content,
+            });
+        }
+        return contentChanged;
+    }
+    deleteFile(filePath) {
+        const documentState = this.documents.get()[filePath];
+        if (!documentState) {
+            return false;
+        }
+        this.documents.setKey(filePath, undefined);
+        return true;
+    }
+    onDocumentChanged(filePath, callback) {
+        const unsubscribeFromCurrentDocument = this.currentDocument.subscribe((document) => {
+            if (document?.filePath === filePath) {
+                callback(document);
+            }
+        });
+        const unsubscribeFromDocuments = this.documents.subscribe((documents) => {
+            const document = documents[filePath];
+            /**
+             * We grab the document from the store, but only call the callback if it is not loading anymore which means
+             * the content is loaded.
+             */
+            if (document && !document.loading) {
+                /**
+                 * Call this in a `queueMicrotask` because the subscribe callback is called synchronoulsy,
+                 * which causes the `unsubscribeFromDocuments` to not exist yet.
+                 */
+                queueMicrotask(() => {
+                    callback(document);
+                    unsubscribeFromDocuments();
+                });
+            }
+        });
+        return () => {
+            unsubscribeFromDocuments();
+            unsubscribeFromCurrentDocument();
+        };
+    }
+}

package/dist/store/index.d.ts

@@ -0,0 +1,113 @@
+import type { FileDescriptor, Lesson } from '@tutorialkit-rb/types';
+import type { WebContainer } from '@webcontainer/api';
+import { type ReadableAtom } from 'nanostores';
+import type { ITerminal } from '../utils/terminal.js';
+import type { EditorConfig } from '../webcontainer/editor-config.js';
+import { type BootStatus } from '../webcontainer/on-demand-boot.js';
+import type { PreviewInfo } from '../webcontainer/preview-info.js';
+import type { TerminalConfig } from '../webcontainer/terminal-config.js';
+import { type EditorDocument, type EditorDocuments, type ScrollPosition } from './editor.js';
+interface StoreOptions {
+    webcontainer: Promise<WebContainer>;
+    /**
+     * Whether or not authentication is used for the WebContainer API.
+     */
+    useAuth: boolean;
+    /**
+     * The base path to use when fetching files.
+     */
+    basePathname?: string;
+}
+export declare class TutorialStore {
+    private _webcontainer;
+    private _runner;
+    private _previewsStore;
+    private _editorStore;
+    private _terminalStore;
+    private _stepController;
+    private _lessonFilesFetcher;
+    private _lessonTask;
+    private _lesson;
+    private _ref;
+    private _themeRef;
+    private _lessonFiles;
+    private _lessonSolution;
+    private _lessonTemplate;
+    /**
+     * Whether or not the current lesson is fully loaded in WebContainer
+     * and in every stores.
+     */
+    readonly lessonFullyLoaded: import("nanostores").WritableAtom<boolean>;
+    constructor({ useAuth, webcontainer, basePathname }: StoreOptions);
+    /** @internal */
+    setLesson(lesson: Lesson, options?: {
+        ssr?: boolean;
+    }): void;
+    /** Instances of the preview tabs. */
+    get previews(): ReadableAtom<PreviewInfo[]>;
+    /** Configuration and instances of the terminal */
+    get terminalConfig(): ReadableAtom<TerminalConfig>;
+    /** Configuration of the editor and file tree */
+    get editorConfig(): ReadableAtom<EditorConfig>;
+    /** File that's currently open in the editor */
+    get currentDocument(): ReadableAtom<EditorDocument | undefined>;
+    /** Status of the webcontainer's booting */
+    get bootStatus(): ReadableAtom<BootStatus>;
+    /** Files that are available in the editor. */
+    get documents(): ReadableAtom<EditorDocuments>;
+    /** Paths of the files that are available in the lesson */
+    get files(): ReadableAtom<FileDescriptor[]>;
+    /** File that's currently selected in the file tree */
+    get selectedFile(): ReadableAtom<string | undefined>;
+    /** Currently active lesson */
+    get lesson(): Readonly<Lesson> | undefined;
+    /** @internal */
+    get ref(): ReadableAtom<unknown>;
+    /** @internal */
+    get themeRef(): ReadableAtom<unknown>;
+    /**
+     * Steps that the runner is or will be executing.
+     *
+     * @internal
+     */
+    get steps(): import("nanostores").WritableAtom<import("../webcontainer/steps.js").Steps | undefined>;
+    /** Check if file tree is visible */
+    hasFileTree(): boolean;
+    /** Check if editor is visible */
+    hasEditor(): boolean;
+    /** Check if lesson has any previews set */
+    hasPreviews(): boolean;
+    /** Check if lesson has any terminals set */
+    hasTerminalPanel(): boolean;
+    /** Check if lesson has solution files set */
+    hasSolution(): boolean;
+    /** Unlock webcontainer's boot process if it was in `'blocked'` state */
+    unblockBoot(): void;
+    /** Reset changed files back to lesson's initial state */
+    reset(): void;
+    /** Apply lesson solution into the lesson files */
+    solve(): void;
+    /** Set file from file tree as selected */
+    setSelectedFile(filePath: string | undefined): void;
+    /** Add new file to file tree */
+    addFile(filePath: string): Promise<void>;
+    /** Add new folder to file tree */
+    addFolder(folderPath: string): Promise<void>;
+    /** Update contents of file */
+    updateFile(filePath: string, content: string): void;
+    /** Update content of the active file */
+    setCurrentDocumentContent(newContent: string): void;
+    /** Update scroll position of the file in editor */
+    setCurrentDocumentScrollPosition(position: ScrollPosition): void;
+    /** @internal */
+    attachTerminal(id: string, terminal: ITerminal): void;
+    /** Callback that should be called when terminal resizes */
+    onTerminalResize(cols: number, rows: number): void;
+    /** Listen for file changes made in the editor */
+    onDocumentChanged(filePath: string, callback: (document: Readonly<EditorDocument>) => void): () => void;
+    /** Take snapshot of the current state of the lesson */
+    takeSnapshot(): {
+        files: Record<string, string>;
+    };
+}
+export {};