@kubohiroya/turbowarp-title-menu 0.1.0

package/src/extension.ts

@@ -0,0 +1,252 @@
+import {createAppShellApplicationMenu, resolveAppShellLocale} from '@kubohiroya/turbowarp-app-shell';
+
+import definitions from './block-definitions.json';
+import {extensionConfig} from './config';
+import {createDslFilesDialog, type DslFilesDialog} from './dsl-files-dialog';
+import {createDslStore, readDslFile, type DslFileRecord, type DslStore} from './dsl-store';
+import {dispatchDslSourceEvent, dslOpenEventName, dslReloadEventName} from './events';
+import {
+  describeStoreError,
+  dslFilesLocales,
+  menuLocales,
+  titleLocales,
+  type SupportedLocale
+} from './locales';
+import {createTitleDialog, type TitleDialog} from './title-dialog';
+
+type ApplicationMenu = ReturnType<typeof createAppShellApplicationMenu>;
+
+type BlockTypeName = 'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT';
+type ArgumentTypeName = 'STRING';
+
+interface DefinitionArgument {
+  type: ArgumentTypeName;
+  defaultValue: string;
+}
+
+interface BlockDefinition {
+  opcode: string;
+  blockType: BlockTypeName;
+  text: string;
+  description: string;
+  arguments?: Record<string, DefinitionArgument>;
+}
+
+const blockDefinitions = definitions.blocks as readonly BlockDefinition[];
+
+const dslFileAccept = '.txt,.yaml,.yml,.json,.k4,.kamishibai';
+
+function stageMount(): HTMLElement | undefined {
+  return Scratch.vm?.renderer?.canvas?.parentElement ?? globalThis.document?.body;
+}
+
+export class TurboWarpTitleMenuExtension implements TurboWarpExtension {
+  private titleDialog: TitleDialog | null = null;
+  private applicationMenu: ApplicationMenu | null = null;
+  private filesDialog: DslFilesDialog | null = null;
+  private store: DslStore | null = null;
+  private openedRecord: DslFileRecord | null = null;
+  private lastError = '';
+
+  public getInfo(): Record<string, unknown> {
+    return {
+      id: extensionConfig.id,
+      name: Scratch.translate(definitions.extensionName),
+      docsURI: extensionConfig.docsURI,
+      blockIconURI: extensionConfig.blockIconURI,
+      blocks: blockDefinitions.map((block) => this.toScratchBlock(block))
+    };
+  }
+
+  public showTitle(): void {
+    this.ensureTitleDialog().show(this.locale());
+  }
+
+  public showMenu(): void {
+    this.ensureApplicationMenu().show(this.locale());
+  }
+
+  public showDslFiles(): Promise<unknown> {
+    return this.ensureFilesDialog().show(this.locale());
+  }
+
+  /** The hat is started by the open path, so its own handler only has to accept the match. */
+  public whenDslSourceOpened(): boolean {
+    return true;
+  }
+
+  public reloadOpenedDsl(): void {
+    if (this.openedRecord === null) return;
+    this.announce(dslReloadEventName, this.openedRecord);
+  }
+
+  public openedDslName(): string {
+    return this.openedRecord?.name ?? '';
+  }
+
+  public openedDslSource(): string {
+    return this.openedRecord?.source ?? '';
+  }
+
+  public async hasSavedDsl(): Promise<boolean> {
+    return (await this.savedDslCount()) > 0;
+  }
+
+  public async savedDslCount(): Promise<number> {
+    try {
+      return await this.requireStore().count();
+    } catch (error) {
+      this.recordFailure(error);
+      return 0;
+    }
+  }
+
+  public lastDslError(): string {
+    return this.lastError;
+  }
+
+  private locale(): SupportedLocale {
+    return resolveAppShellLocale() === 'ja' ? 'ja' : 'en';
+  }
+
+  /**
+   * Opens the store on first use.
+   *
+   * A browser without IndexedDB, or one with storage blocked, fails here rather than at extension
+   * load: the title and menu blocks stay usable even when nothing can be stored.
+   */
+  private requireStore(): DslStore {
+    this.store ??= createDslStore({databaseName: extensionConfig.id});
+    return this.store;
+  }
+
+  private recordFailure(error: unknown): void {
+    this.lastError = describeStoreError(this.locale(), error);
+  }
+
+  private announce(eventName: string, record: DslFileRecord): void {
+    dispatchDslSourceEvent(eventName, record);
+    Scratch.vm?.runtime?.startHats?.(`${extensionConfig.id}_whenDslSourceOpened`);
+  }
+
+  private ensureTitleDialog(): TitleDialog {
+    if (this.titleDialog) return this.titleDialog;
+    const mount = stageMount();
+    this.titleDialog = createTitleDialog({
+      document: globalThis.document,
+      ...(mount ? {mount} : {}),
+      locales: titleLocales,
+      initialLocale: this.locale(),
+      websiteUrl: extensionConfig.homepage
+    });
+    return this.titleDialog;
+  }
+
+  /**
+   * Builds the menu from the shared app-shell primitive.
+   *
+   * The actions below are this extension's own vocabulary, not the primitive's: a host application
+   * that needs different actions composes `createAppShellApplicationMenu` itself through the
+   * composition API instead of being limited to these four.
+   */
+  private ensureApplicationMenu(): ApplicationMenu {
+    if (this.applicationMenu) return this.applicationMenu;
+    const mount = stageMount();
+    if (mount === undefined) throw new TypeError('a stage container is required to show the menu');
+    const labels = (key: keyof (typeof menuLocales)['en']) => ({
+      en: menuLocales.en[key],
+      ja: menuLocales.ja[key]
+    });
+    this.applicationMenu = createAppShellApplicationMenu({
+      document: globalThis.document,
+      mount,
+      initialLocale: this.locale(),
+      actions: [
+        {id: 'files', labels: labels('files'), icon: {text: '\u{1F4C2}'}, onSelect: () => this.showDslFiles()},
+        {id: 'reload', labels: labels('reload'), icon: {text: '↻'}, onSelect: () => this.reloadOpenedDsl()},
+        {id: 'about', labels: labels('about'), icon: {text: 'i'}, onSelect: () => this.showTitle()},
+        {id: 'close', labels: labels('close'), icon: {text: 'x'}, onSelect: () => this.applicationMenu?.hide()}
+      ]
+    });
+    return this.applicationMenu;
+  }
+
+  private ensureFilesDialog(): DslFilesDialog {
+    if (this.filesDialog) return this.filesDialog;
+    const mount = stageMount();
+    this.filesDialog = createDslFilesDialog({
+      document: globalThis.document,
+      ...(mount ? {mount} : {}),
+      locales: dslFilesLocales,
+      initialLocale: this.locale(),
+      list: (sort) => this.requireStore().list(sort),
+      onAdd: () => this.addDslFile(),
+      onOpen: (id) => this.openDslFile(id),
+      onRename: (id, name) => this.requireStore().rename(id, name),
+      onRemove: (id) => this.removeDslFile(id),
+      describeError: (error) => describeStoreError(this.locale(), error),
+      onError: (error) => this.recordFailure(error)
+    });
+    return this.filesDialog;
+  }
+
+  private async addDslFile(): Promise<void> {
+    const chosen = await this.pickDslFile();
+    if (chosen === null) return;
+    await this.requireStore().save(await readDslFile(chosen));
+    this.lastError = '';
+  }
+
+  private async openDslFile(id: string): Promise<void> {
+    const store = this.requireStore();
+    const record = await store.get(id);
+    if (record === null) return;
+    await store.markOpened(id);
+    this.openedRecord = record;
+    this.lastError = '';
+    this.announce(dslOpenEventName, record);
+  }
+
+  private async removeDslFile(id: string): Promise<void> {
+    await this.requireStore().remove(id);
+    if (this.openedRecord?.id === id) this.openedRecord = null;
+    this.lastError = '';
+  }
+
+  private pickDslFile(): Promise<File | null> {
+    const document = globalThis.document;
+    if (!document) throw new TypeError('document is required to open a DSL file');
+    const input = document.createElement('input');
+    input.type = 'file';
+    input.accept = dslFileAccept;
+    return new Promise<File | null>((resolve) => {
+      input.addEventListener(
+        'change',
+        () => {
+          resolve(input.files?.[0] ?? null);
+        },
+        {once: true}
+      );
+      input.click();
+    });
+  }
+
+  private toScratchBlock(block: BlockDefinition): Record<string, unknown> {
+    const scratchBlock: Record<string, unknown> = {
+      opcode: block.opcode,
+      blockType: Scratch.BlockType[block.blockType],
+      text: Scratch.translate(block.text),
+      arguments: Object.fromEntries(
+        Object.entries(block.arguments ?? {}).map(([name, argument]) => [
+          name,
+          {
+            type: Scratch.ArgumentType[argument.type],
+            defaultValue: argument.defaultValue
+          }
+        ])
+      )
+    };
+    if (block.blockType === 'HAT') scratchBlock['isEdgeActivated'] = false;
+    return scratchBlock;
+  }
+}

package/src/globals.d.ts

@@ -0,0 +1,33 @@
+interface TurboWarpExtension {
+  getInfo(): Record<string, unknown>;
+}
+
+interface ScratchTranslate {
+  (text: string): string;
+  (message: {default: string; description?: string}, placeholders?: Record<string, string | number>): string;
+}
+
+interface ScratchApi {
+  extensions: {
+    unsandboxed: boolean;
+    register(extension: TurboWarpExtension): void;
+  };
+  vm?: {
+    renderer?: {
+      canvas?: HTMLCanvasElement;
+    };
+    runtime?: {
+      startHats?(opcode: string, matchFields?: Record<string, unknown>): unknown;
+    };
+  };
+  BlockType: Record<'COMMAND' | 'REPORTER' | 'BOOLEAN' | 'HAT', string>;
+  ArgumentType: Record<'STRING' | 'NUMBER' | 'BOOLEAN', string>;
+  Cast: {
+    toString(value: unknown): string;
+    toNumber(value: unknown): number;
+    toBoolean(value: unknown): boolean;
+  };
+  translate: ScratchTranslate;
+}
+
+declare const Scratch: ScratchApi;

package/src/index.ts

@@ -0,0 +1,28 @@
+import {createAppShellApplicationMenu} from '@kubohiroya/turbowarp-app-shell';
+
+import {extensionConfig} from './config.js';
+import {createDslFilesDialog} from './dsl-files-dialog.js';
+import {createDslStore} from './dsl-store.js';
+import {dslOpenEventName, dslReloadEventName} from './events.js';
+import {createTitleDialog} from './title-dialog.js';
+import {TurboWarpTitleMenuExtension} from './extension.js';
+
+const publicApi = Object.freeze({
+  createApplicationMenu: createAppShellApplicationMenu,
+  createDslFilesDialog,
+  createDslStore,
+  createTitleDialog,
+  dslOpenEventName,
+  dslReloadEventName
+});
+
+Object.defineProperty(globalThis, 'TurboWarpTitleMenu', {
+  value: publicApi,
+  configurable: true
+});
+
+if (extensionConfig.unsandboxed && !Scratch.extensions.unsandboxed) {
+  throw new Error(`${extensionConfig.name} must run unsandboxed.`);
+}
+
+Scratch.extensions.register(new TurboWarpTitleMenuExtension());

package/src/locales.ts

@@ -0,0 +1,103 @@
+import type {DslFilesDialogLocaleText} from './dsl-files-dialog';
+import type {DslStoreErrorCode} from './dsl-store';
+import type {TitleDialogLocaleText} from './title-dialog';
+
+export type SupportedLocale = 'en' | 'ja';
+
+export interface MenuActionLabels {
+  files: string;
+  reload: string;
+  about: string;
+  close: string;
+}
+
+export const titleLocales: Readonly<Record<SupportedLocale, TitleDialogLocaleText>> = Object.freeze({
+  en: {
+    title: 'TurboWarp Title Menu',
+    author: 'Author: Hiroya Kubo',
+    license: 'License: MPL-2.0',
+    website: 'Official Website',
+    close: 'Close'
+  },
+  ja: {
+    title: 'TurboWarp Title Menu',
+    author: '作者: Hiroya Kubo',
+    license: 'ライセンス: MPL-2.0',
+    website: '公式Webサイト',
+    close: '閉じる'
+  }
+});
+
+export const menuLocales: Readonly<Record<SupportedLocale, MenuActionLabels>> = Object.freeze({
+  en: {files: 'DSL files', reload: 'Reload DSL', about: 'About', close: 'Close'},
+  ja: {files: 'DSLファイル', reload: 'DSLを再読み込み', about: '情報', close: '閉じる'}
+});
+
+export const dslFilesLocales: Readonly<Record<SupportedLocale, DslFilesDialogLocaleText>> =
+  Object.freeze({
+    en: {
+      title: 'DSL files',
+      add: 'Add file',
+      open: 'Open',
+      rename: 'Rename',
+      remove: 'Delete',
+      confirmRemove: 'Delete for good?',
+      confirm: 'OK',
+      cancel: 'Cancel',
+      close: 'Close',
+      sortByName: 'Name',
+      sortByDate: 'Updated',
+      sortBySize: 'Size',
+      empty: 'No DSL file is saved yet. Use Add file to store one.'
+    },
+    ja: {
+      title: 'DSLファイル',
+      add: 'ファイルを追加',
+      open: '開く',
+      rename: '名前を変える',
+      remove: '削除',
+      confirmRemove: '本当に削除?',
+      confirm: 'OK',
+      cancel: 'やめる',
+      close: '閉じる',
+      sortByName: '名前',
+      sortByDate: '更新日時',
+      sortBySize: 'サイズ',
+      empty: '保存されたDSLファイルはありません。「ファイルを追加」から保存してください。'
+    }
+  });
+
+const storeErrorMessages: Readonly<Record<SupportedLocale, Record<DslStoreErrorCode, string>>> =
+  Object.freeze({
+    en: {
+      unavailable: 'Browser storage is unavailable, so DSL files cannot be saved.',
+      'invalid-name': 'That file name cannot be used.',
+      'invalid-source': 'That file could not be read as text.',
+      'name-taken': 'Another DSL file already uses that name.',
+      'too-large': 'That DSL file is too large to store.',
+      'too-many': 'The DSL store is full. Delete a file before adding another.',
+      'not-found': 'That DSL file is no longer stored.',
+      quota: 'Browser storage is full. Delete a DSL file and try again.',
+      failed: 'The DSL storage operation failed.'
+    },
+    ja: {
+      unavailable: 'ブラウザの保存領域が使えないため、DSLファイルを保存できません。',
+      'invalid-name': 'そのファイル名は使えません。',
+      'invalid-source': 'そのファイルをテキストとして読み込めませんでした。',
+      'name-taken': '同じ名前のDSLファイルがすでにあります。',
+      'too-large': 'そのDSLファイルは大きすぎて保存できません。',
+      'too-many': '保存できる数に達しています。どれかを削除してから追加してください。',
+      'not-found': 'そのDSLファイルは保存されていません。',
+      quota: 'ブラウザの保存領域がいっぱいです。DSLファイルを削除してからやり直してください。',
+      failed: 'DSLファイルの操作に失敗しました。'
+    }
+  });
+
+/** Turns a store error code into operator-facing text, falling back to the raw message. */
+export function describeStoreError(locale: SupportedLocale, error: unknown): string {
+  const code = (error as {code?: DslStoreErrorCode} | null)?.code;
+  const messages = storeErrorMessages[locale] ?? storeErrorMessages.en;
+  if (code !== undefined && code in messages) return messages[code];
+  if (error instanceof Error && error.message.length > 0) return error.message;
+  return String(error);
+}

package/src/title-dialog.ts

@@ -0,0 +1,168 @@
+import {ensureRelativeMount, invokeSafely, requireDocument, requireElement} from './dom';
+
+export type TitleMenuLocale = string;
+
+export interface TitleDialogLocaleText {
+  title: string;
+  author?: string;
+  license?: string;
+  website: string;
+  close: string;
+  language?: string;
+}
+
+export interface TitleDialogOptions {
+  document?: Document;
+  mount?: HTMLElement;
+  locales: Record<string, TitleDialogLocaleText>;
+  initialLocale?: TitleMenuLocale;
+  websiteUrl?: string;
+  onWebsite?: () => unknown | Promise<unknown>;
+  onClose?: () => unknown | Promise<unknown>;
+  onLocaleChange?: (locale: TitleMenuLocale) => unknown | Promise<unknown>;
+  onError?: (error: unknown) => void;
+}
+
+export interface TitleDialog {
+  readonly element: HTMLElement;
+  readonly locale: TitleMenuLocale;
+  show(locale?: TitleMenuLocale): TitleMenuLocale;
+  hide(): void;
+  setLocale(locale: TitleMenuLocale): TitleMenuLocale;
+  dispose(): void;
+}
+
+function requireLocaleText(locales: Record<string, TitleDialogLocaleText>, locale: string): TitleDialogLocaleText {
+  const text = locales[locale] ?? locales.en ?? Object.values(locales)[0];
+  if (!text) throw new TypeError('locales must contain at least one locale');
+  for (const key of ['title', 'website', 'close'] as const) {
+    if (typeof text[key] !== 'string' || text[key].length === 0) {
+      throw new TypeError(`locales.${locale}.${key} must be a non-empty string`);
+    }
+  }
+  return text;
+}
+
+function openWebsite(url: string): void {
+  const opener = globalThis.open;
+  if (typeof opener === 'function') {
+    opener(url, '_blank', 'noopener,noreferrer');
+  } else if (globalThis.location) {
+    globalThis.location.href = url;
+  }
+}
+
+export function createTitleDialog(options: TitleDialogOptions): TitleDialog {
+  const document = requireDocument(options.document ?? globalThis.document);
+  const mount = requireElement(options.mount ?? document.body, 'mount');
+  const locales = options.locales;
+  if (!locales || typeof locales !== 'object') throw new TypeError('locales must be an object');
+
+  const root = document.createElement('section');
+  const panel = document.createElement('div');
+  const language = document.createElement('button');
+  const close = document.createElement('button');
+  const heading = document.createElement('h1');
+  const meta = document.createElement('p');
+  const website = document.createElement('button');
+  root.setAttribute('data-turbowarp-title-dialog', 'true');
+  root.setAttribute('role', 'dialog');
+  root.setAttribute('aria-modal', 'true');
+  root.style.cssText =
+    'position:absolute;inset:0;z-index:2147483647;display:none;align-items:center;justify-content:center;box-sizing:border-box;background:rgba(0,0,0,.35);font-family:sans-serif;';
+  panel.style.cssText =
+    'position:relative;box-sizing:border-box;width:min(88%,420px);padding:36px 28px 28px;text-align:center;background:#f4fffb;border:1px solid #007d66;border-radius:12px;box-shadow:0 8px 32px rgba(0,0,0,.3);color:#006b58;';
+  language.style.cssText =
+    'position:absolute;top:14px;left:16px;border:0;background:transparent;color:#007d66;font-size:14px;cursor:pointer;';
+  close.style.cssText =
+    'position:absolute;top:12px;right:12px;width:32px;height:32px;border:0;border-radius:50%;background:#007d66;color:#fff;font-size:22px;line-height:28px;cursor:pointer;';
+  heading.style.cssText = 'margin:0 24px 8px;font-size:30px;font-weight:600;line-height:1.15;';
+  meta.style.cssText = 'margin:0 0 22px;font-size:14px;line-height:1.4;';
+  website.style.cssText =
+    'display:inline-flex;align-items:center;justify-content:center;min-height:48px;padding:8px 18px;border:0;border-radius:10px;background:#007d66;color:#fff;font-size:16px;cursor:pointer;';
+  language.type = 'button';
+  close.type = 'button';
+  website.type = 'button';
+  close.textContent = 'x';
+
+  panel.append(language, close, heading, meta, website);
+  root.appendChild(panel);
+  const restoreMount = ensureRelativeMount(mount);
+  mount.appendChild(root);
+
+  let locale = options.initialLocale ?? (locales.ja ? 'ja' : Object.keys(locales)[0] ?? 'en');
+  let disposed = false;
+
+  const render = (): void => {
+    const text = requireLocaleText(locales, locale);
+    heading.textContent = text.title;
+    meta.textContent = [text.author, text.license].filter(Boolean).join(' / ');
+    meta.hidden = meta.textContent.length === 0;
+    website.textContent = text.website;
+    website.setAttribute('aria-label', text.website);
+    close.setAttribute('aria-label', text.close);
+    close.setAttribute('title', text.close);
+    language.textContent = text.language ?? locale;
+    language.setAttribute('aria-label', text.language ?? locale);
+  };
+
+  const handleWebsite = (): void => {
+    if (options.onWebsite) invokeSafely(options.onWebsite, options.onError);
+    else if (options.websiteUrl) openWebsite(options.websiteUrl);
+  };
+  const handleClose = (): void => {
+    hide();
+    if (options.onClose) invokeSafely(options.onClose, options.onError);
+  };
+  const handleLanguage = (): void => {
+    const keys = Object.keys(locales);
+    locale = keys[(Math.max(keys.indexOf(locale), 0) + 1) % keys.length] ?? locale;
+    render();
+    if (options.onLocaleChange) invokeSafely(() => options.onLocaleChange?.(locale), options.onError);
+  };
+
+  website.addEventListener('click', handleWebsite);
+  close.addEventListener('click', handleClose);
+  language.addEventListener('click', handleLanguage);
+
+  function show(nextLocale = locale): TitleMenuLocale {
+    if (disposed) throw new TypeError('title dialog is disposed');
+    locale = nextLocale;
+    render();
+    root.style.display = 'flex';
+    return locale;
+  }
+
+  function hide(): void {
+    if (!disposed) root.style.display = 'none';
+  }
+
+  function setLocale(nextLocale: TitleMenuLocale): TitleMenuLocale {
+    if (disposed) throw new TypeError('title dialog is disposed');
+    locale = nextLocale;
+    render();
+    return locale;
+  }
+
+  function dispose(): void {
+    if (disposed) return;
+    disposed = true;
+    website.removeEventListener('click', handleWebsite);
+    close.removeEventListener('click', handleClose);
+    language.removeEventListener('click', handleLanguage);
+    root.remove();
+    restoreMount();
+  }
+
+  render();
+  return Object.freeze({
+    element: root,
+    get locale() {
+      return locale;
+    },
+    show,
+    hide,
+    setLocale,
+    dispose
+  });
+}