@autono/open-pages 0.1.0

package/src/app/lib/folders.ts

@@ -0,0 +1,239 @@
+import buildManifest from 'virtual:open-pages/folders';
+import { useCallback, useEffect, useState } from 'react';
+import type { Folder, FolderIcon, FoldersManifest } from './sdk';
+
+const EMPTY: FoldersManifest = { folders: [], assignments: {} };
+
+async function getManifest(): Promise<FoldersManifest> {
+  // In dev the manifest is mutable: read live from the plugin endpoint so
+  // edits made in the sidebar reflect immediately. In a static build there
+  // is no server, so fall back to the bundled snapshot from the virtual
+  // module (populated at build time from pages/.folders.json).
+  if (import.meta.env.DEV) {
+    const res = await fetch('/__folders');
+    if (!res.ok) throw new Error(`GET /__folders ${res.status}`);
+    const raw = (await res.json()) as Partial<FoldersManifest>;
+    return {
+      folders: raw.folders ?? [],
+      assignments: raw.assignments ?? {},
+    };
+  }
+  return {
+    folders: buildManifest.folders ?? [],
+    assignments: buildManifest.assignments ?? {},
+  };
+}
+
+async function patchDocName(pageId: string, name: string): Promise<void> {
+  const res = await fetch(`/__pages/${pageId}`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name }),
+  });
+  if (!res.ok) throw new Error(`PATCH /__pages/${pageId} ${res.status}`);
+}
+
+async function duplicateDocReq(pageId: string, newId?: string): Promise<string> {
+  const init: RequestInit = { method: 'POST' };
+  if (newId !== undefined) {
+    init.headers = { 'content-type': 'application/json' };
+    init.body = JSON.stringify({ newId });
+  }
+  const res = await fetch(`/__pages/${pageId}/duplicate`, init);
+  if (!res.ok) throw new Error(`POST /__pages/${pageId}/duplicate ${res.status}`);
+  const body = (await res.json()) as { pageId?: unknown };
+  if (typeof body.pageId !== 'string') throw new Error('duplicate response missing pageId');
+  return body.pageId;
+}
+
+async function deleteDocReq(pageId: string): Promise<void> {
+  const res = await fetch(`/__pages/${pageId}`, { method: 'DELETE' });
+  if (!res.ok) throw new Error(`DELETE /__pages/${pageId} ${res.status}`);
+}
+
+async function postFolder(name: string, icon: FolderIcon): Promise<Folder> {
+  const res = await fetch('/__folders', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name, icon }),
+  });
+  if (!res.ok) throw new Error(`POST /__folders ${res.status}`);
+  return (await res.json()) as Folder;
+}
+
+async function patchFolder(
+  id: string,
+  patch: { name?: string; icon?: FolderIcon },
+): Promise<Folder> {
+  const res = await fetch(`/__folders/${id}`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(patch),
+  });
+  if (!res.ok) throw new Error(`PATCH /__folders/${id} ${res.status}`);
+  return (await res.json()) as Folder;
+}
+
+async function deleteFolder(id: string): Promise<void> {
+  const res = await fetch(`/__folders/${id}`, { method: 'DELETE' });
+  if (!res.ok) throw new Error(`DELETE /__folders/${id} ${res.status}`);
+}
+
+async function putAssign(pageId: string, folderId: string | null): Promise<void> {
+  const res = await fetch('/__folders/assign', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ pageId, folderId }),
+  });
+  if (!res.ok) throw new Error(`PUT /__folders/assign ${res.status}`);
+}
+
+async function putReorder(ids: string[]): Promise<void> {
+  const res = await fetch('/__folders/reorder', {
+    method: 'PUT',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ ids }),
+  });
+  if (!res.ok) throw new Error(`PUT /__folders/reorder ${res.status}`);
+}
+
+export type UseFoldersResult = {
+  manifest: FoldersManifest;
+  loading: boolean;
+  create: (name: string, icon: FolderIcon) => Promise<Folder>;
+  update: (id: string, patch: { name?: string; icon?: FolderIcon }) => Promise<void>;
+  remove: (id: string) => Promise<void>;
+  reorder: (ids: string[]) => Promise<void>;
+  assign: (pageId: string, folderId: string | null) => Promise<void>;
+  renameDoc: (pageId: string, name: string) => Promise<void>;
+  duplicatePage: (pageId: string, newId?: string) => Promise<string>;
+  deletePage: (pageId: string) => Promise<void>;
+  refresh: () => Promise<void>;
+};
+
+export function useFolders(): UseFoldersResult {
+  const [manifest, setManifest] = useState<FoldersManifest>(EMPTY);
+  const [loading, setLoading] = useState(true);
+
+  const refresh = useCallback(async () => {
+    const m = await getManifest();
+    setManifest(m);
+  }, []);
+
+  useEffect(() => {
+    let cancelled = false;
+    getManifest()
+      .then((m) => {
+        if (!cancelled) {
+          setManifest(m);
+          setLoading(false);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!import.meta.hot) return;
+    const handler = () => {
+      refresh().catch(() => {});
+    };
+    import.meta.hot.on('open-pages:files-changed', handler);
+    return () => {
+      import.meta.hot?.off('open-pages:files-changed', handler);
+    };
+  }, [refresh]);
+
+  const create = useCallback(
+    async (name: string, icon: FolderIcon) => {
+      const folder = await postFolder(name, icon);
+      await refresh();
+      return folder;
+    },
+    [refresh],
+  );
+
+  const update = useCallback(
+    async (id: string, patch: { name?: string; icon?: FolderIcon }) => {
+      await patchFolder(id, patch);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const remove = useCallback(
+    async (id: string) => {
+      await deleteFolder(id);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const reorder = useCallback(
+    async (ids: string[]) => {
+      const prev = manifest;
+      const byId = new Map(prev.folders.map((f) => [f.id, f]));
+      const next = ids.map((id) => byId.get(id)).filter((f): f is Folder => Boolean(f));
+      if (next.length !== prev.folders.length) return;
+      setManifest({ ...prev, folders: next });
+      try {
+        await putReorder(ids);
+      } catch (err) {
+        setManifest(prev);
+        throw err;
+      }
+    },
+    [manifest],
+  );
+
+  const assign = useCallback(
+    async (pageId: string, folderId: string | null) => {
+      await putAssign(pageId, folderId);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const renameDoc = useCallback(
+    async (pageId: string, name: string) => {
+      await patchDocName(pageId, name);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  const duplicatePage = useCallback(
+    async (pageId: string, newId?: string) => {
+      const duplicatedId = await duplicateDocReq(pageId, newId);
+      await refresh();
+      return duplicatedId;
+    },
+    [refresh],
+  );
+
+  const deletePage = useCallback(
+    async (pageId: string) => {
+      await deleteDocReq(pageId);
+      await refresh();
+    },
+    [refresh],
+  );
+
+  return {
+    manifest,
+    loading,
+    create,
+    update,
+    remove,
+    reorder,
+    assign,
+    renameDoc,
+    duplicatePage,
+    deletePage,
+    refresh,
+  };
+}

package/src/app/lib/frame.ts

@@ -0,0 +1,38 @@
+import type { PageKind } from './sdk';
+
+/** Messages the page frame posts to the workspace window. */
+export type FrameMessage =
+  | { type: 'op:ready'; title: string }
+  | { type: 'op:error'; message: string }
+  | { type: 'op:select'; loc: string; tag: string; text: string }
+  | { type: 'op:key'; key: string };
+
+/** Messages the workspace posts into the page frame. */
+export type WorkspaceMessage =
+  | { type: 'op:inspect'; on: boolean }
+  | { type: 'op:select'; loc: string | null };
+
+export type FrameSource = { pageId: string; kind?: PageKind } | { themeId: string };
+
+const BASE = import.meta.env.BASE_URL;
+
+/**
+ * URL the workspace loads into an iframe for a page or a theme demo. React
+ * pages mount through `frame.html`; `index.html` pages are served verbatim
+ * (dev middleware, or the per-page build under `__page/` in a static build).
+ */
+export function frameUrl(source: FrameSource): string {
+  if ('themeId' in source) return `${BASE}frame.html?theme=${encodeURIComponent(source.themeId)}`;
+  if (source.kind === 'html')
+    return `${BASE}__page/${encodeURIComponent(source.pageId)}/index.html`;
+  return `${BASE}frame.html?page=${encodeURIComponent(source.pageId)}`;
+}
+
+export function isFrameMessage(data: unknown): data is FrameMessage {
+  return (
+    !!data &&
+    typeof data === 'object' &&
+    typeof (data as { type?: unknown }).type === 'string' &&
+    (data as { type: string }).type.startsWith('op:')
+  );
+}

package/src/app/lib/locale-store.ts

@@ -0,0 +1,67 @@
+import config from 'virtual:open-pages/config';
+import { useSyncExternalStore } from 'react';
+import { en } from '../../locale/en';
+import { ja } from '../../locale/ja';
+import type { Locale } from '../../locale/types';
+import { zhCN } from '../../locale/zh-cn';
+import { zhTW } from '../../locale/zh-tw';
+
+export type LocaleId = Locale['id'];
+
+const LOCALES: Record<LocaleId, Locale> = {
+  en,
+  'zh-TW': zhTW,
+  'zh-CN': zhCN,
+  ja,
+};
+
+export const LOCALE_OPTIONS: ReadonlyArray<{ id: LocaleId; label: string }> = [
+  { id: 'en', label: 'English' },
+  { id: 'zh-TW', label: '繁體中文' },
+  { id: 'zh-CN', label: '简体中文' },
+  { id: 'ja', label: '日本語' },
+];
+
+const STORAGE_KEY = 'open-pages:locale';
+const configLocale = config.locale as Locale | undefined;
+
+function isLocaleId(value: string | null): value is LocaleId {
+  return value === 'en' || value === 'zh-TW' || value === 'zh-CN' || value === 'ja';
+}
+
+function readStored(): Locale {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (isLocaleId(stored)) return LOCALES[stored];
+  } catch {}
+  return configLocale ?? en;
+}
+
+// A module-level store (rather than React context) so every React root the
+// runtime mounts — the app shell plus the standalone roots used for HTML/PDF
+// export — shares one locale without needing a provider above each of them.
+let current: Locale = readStored();
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getSnapshot(): Locale {
+  return current;
+}
+
+export function setLocale(id: LocaleId): void {
+  current = LOCALES[id];
+  try {
+    localStorage.setItem(STORAGE_KEY, id);
+  } catch {}
+  for (const listener of listeners) listener();
+}
+
+export function useLocaleValue(): Locale {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/src/app/lib/page-thumb.tsx

@@ -0,0 +1,46 @@
+import { useEffect, useRef, useState } from 'react';
+import { type FrameSource, frameUrl } from './frame';
+
+const THUMB_VIEWPORT = 1280;
+
+/**
+ * Live page preview for cards: the real page in an iframe laid out at a
+ * desktop width and scaled down to fit. Inert — pointer events go to the
+ * card, and the frame never takes focus.
+ */
+export function PageThumb({ source, title }: { source: FrameSource; title: string }) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const measure = () => setSize({ width: el.clientWidth, height: el.clientHeight });
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  }, []);
+
+  const scale = size.width > 0 ? size.width / THUMB_VIEWPORT : 0;
+
+  return (
+    <div ref={ref} className="h-full w-full overflow-hidden bg-white">
+      {scale > 0 && (
+        <iframe
+          title={title}
+          src={frameUrl(source)}
+          loading="lazy"
+          tabIndex={-1}
+          aria-hidden
+          className="pointer-events-none origin-top-left border-0"
+          style={{
+            width: THUMB_VIEWPORT,
+            height: size.height / scale,
+            transform: `scale(${scale})`,
+          }}
+        />
+      )}
+    </div>
+  );
+}

package/src/app/lib/pages.ts

@@ -0,0 +1,28 @@
+import {
+  pageCreatedAt as createdAt,
+  pageIds as ids,
+  pageKinds as kinds,
+  loadPage as load,
+  pageThemes as themes,
+} from 'virtual:open-pages/pages';
+import type { PageKind, PageModule } from './sdk';
+
+export const pageIds: string[] = ids;
+export const pageKinds: Record<string, PageKind> = kinds;
+export const pageThemes: Record<string, string> = themes;
+export const pageCreatedAt: Record<string, number> = createdAt;
+
+export function pagesByTheme(themeId: string): string[] {
+  return pageIds.filter((id) => pageThemes[id] === themeId);
+}
+
+export async function loadPage(id: string): Promise<PageModule> {
+  return load(id);
+}
+
+export function pageChangeIncludes(data: unknown, pageId: string): boolean {
+  if (!data || typeof data !== 'object') return false;
+  const payload = data as { pageId?: unknown; pageIds?: unknown };
+  if (payload.pageId === pageId) return true;
+  return Array.isArray(payload.pageIds) && payload.pageIds.includes(pageId);
+}

package/src/app/lib/sdk.ts

@@ -0,0 +1,43 @@
+import type { ComponentType } from 'react';
+import type { DesignSystem } from './design.ts';
+
+/**
+ * A page is one React component rendered into a real browser document. It
+ * owns the whole viewport: layout, styling (Tailwind via `className` or a
+ * sibling stylesheet), interactivity, and any client-side routing it wants.
+ */
+export type PageComponent = ComponentType;
+
+export type PageMeta = {
+  /** Document title (browser tab, workspace card). Default: the folder name. */
+  title?: string;
+  /** `<meta name="description">` in the exported HTML. */
+  description?: string;
+  /** Id of a theme under `themes/` this page was built from. */
+  theme?: string;
+  /** ISO 8601 timestamp. Set once at scaffold time; used to sort the page list. */
+  createdAt?: string;
+};
+
+/** How a page entry is authored: a React module or a plain HTML file. */
+export type PageKind = 'react' | 'html';
+
+export type PageModule = {
+  /** Absent for `index.html` pages, which the workspace serves as-is. */
+  default?: PageComponent;
+  meta?: PageMeta;
+  design?: DesignSystem;
+};
+
+export type FolderIcon = { type: 'emoji'; value: string } | { type: 'color'; value: string };
+
+export type Folder = {
+  id: string;
+  name: string;
+  icon: FolderIcon;
+};
+
+export type FoldersManifest = {
+  folders: Folder[];
+  assignments: Record<string, string>;
+};

package/src/app/lib/themes.ts

@@ -0,0 +1,22 @@
+import { loadThemeDemo as load, themes as raw } from 'virtual:open-pages/themes';
+import type { DesignSystem } from './design';
+import type { PageComponent } from './sdk';
+
+export type Theme = {
+  id: string;
+  name: string;
+  description: string;
+  body: string;
+  hasDemo: boolean;
+};
+
+export type ThemeDemoModule = {
+  default: PageComponent;
+  design?: DesignSystem;
+};
+
+export const themes: Theme[] = raw;
+
+export async function loadThemeDemo(id: string): Promise<ThemeDemoModule> {
+  return load(id);
+}

package/src/app/lib/use-locale.ts

@@ -0,0 +1,8 @@
+import type { Locale } from '../../locale/types';
+import { useLocaleValue } from './locale-store';
+
+export function useLocale(): Locale {
+  return useLocaleValue();
+}
+
+export { format, plural } from '../../locale/format';

package/src/app/lib/use-page-module.ts

@@ -0,0 +1,48 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { loadPage, pageChangeIncludes } from './pages';
+import type { PageModule } from './sdk';
+
+export function usePageModule(pageId: string) {
+  const [page, setDoc] = useState<PageModule | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const loadSeqRef = useRef(0);
+
+  const reload = useCallback(
+    (reset: boolean) => {
+      const seq = ++loadSeqRef.current;
+      if (reset) setDoc(null);
+      setError(null);
+      loadPage(pageId)
+        .then((mod) => {
+          if (seq === loadSeqRef.current) setDoc(mod);
+        })
+        .catch((e) => {
+          if (seq === loadSeqRef.current) setError(String(e?.message ?? e));
+        });
+    },
+    [pageId],
+  );
+
+  useEffect(() => {
+    reload(true);
+  }, [reload]);
+
+  useEffect(() => {
+    if (!import.meta.hot) return;
+    let cancelled = false;
+    const handler = (data: unknown) => {
+      if (pageChangeIncludes(data, pageId)) {
+        queueMicrotask(() => {
+          if (!cancelled) reload(false);
+        });
+      }
+    };
+    import.meta.hot.on('open-pages:page-changed', handler);
+    return () => {
+      cancelled = true;
+      import.meta.hot?.off('open-pages:page-changed', handler);
+    };
+  }, [pageId, reload]);
+
+  return { page, error, reload };
+}

package/src/app/lib/use-page-titles.ts

@@ -0,0 +1,29 @@
+import { useEffect, useRef, useState } from 'react';
+import { loadPage, pageIds } from './pages';
+
+/**
+ * Resolves every deck's display title once `enabled` first turns true. The home
+ * grid only mounts the cards of the selected folder, so cross-folder search
+ * needs its own pass over the page modules — kept lazy since it imports them all.
+ */
+export function usePageTitles(enabled: boolean): Record<string, string> {
+  const [titles, setTitles] = useState<Record<string, string>>({});
+  const startedRef = useRef(false);
+
+  useEffect(() => {
+    if (!enabled || startedRef.current) return;
+    startedRef.current = true;
+    void Promise.all(
+      pageIds.map(async (id): Promise<[string, string]> => {
+        try {
+          const mod = await loadPage(id);
+          return [id, mod.meta?.title ?? id];
+        } catch {
+          return [id, id];
+        }
+      }),
+    ).then((entries) => setTitles(Object.fromEntries(entries)));
+  }, [enabled]);
+
+  return titles;
+}

package/src/app/lib/use-restart-server.ts

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useSyncExternalStore } from 'react';
+import { toast } from 'sonner';
+import { useLocale } from '@/lib/use-locale';
+
+type ServerStatus = { executionId: string; canRestart: boolean };
+
+async function fetchServerStatus(): Promise<ServerStatus | null> {
+  const res = await fetch('/__server-status');
+  if (!res.ok) return null;
+  return (await res.json()) as ServerStatus;
+}
+
+// Module scope, not per-hook state: the sidebar footer and the command menu can
+// both be mounted, and each firing its own POST plus polling loop would race.
+let state = { canRestart: false, restarting: false };
+let statusProbed = false;
+let inFlight: Promise<boolean> | null = null;
+const listeners = new Set<() => void>();
+
+function setState(next: Partial<typeof state>): void {
+  state = { ...state, ...next };
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getSnapshot(): typeof state {
+  return state;
+}
+
+async function performRestart(): Promise<boolean> {
+  const before = await fetchServerStatus();
+  if (!before) return false;
+  const res = await fetch('/__restart-server', { method: 'POST' });
+  if (!res.ok) return false;
+  // A different executionId means the replacement process is serving.
+  for (let attempt = 0; attempt < 30; attempt++) {
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    const status = await fetchServerStatus().catch(() => null);
+    if (status && status.executionId !== before.executionId) {
+      window.location.reload();
+      return true;
+    }
+  }
+  return false;
+}
+
+export function useRestartServer() {
+  const t = useLocale();
+  const { canRestart, restarting } = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  useEffect(() => {
+    if (!import.meta.env.DEV || statusProbed) return;
+    statusProbed = true;
+    fetchServerStatus()
+      .then((status) => {
+        if (status) setState({ canRestart: status.canRestart });
+      })
+      .catch(() => {});
+  }, []);
+
+  const restartServer = useCallback(async () => {
+    if (inFlight) return;
+    inFlight = performRestart().catch(() => false);
+    setState({ restarting: true });
+    const restarted = await inFlight;
+    inFlight = null;
+    setState({ restarting: false });
+    if (!restarted) toast.error(t.home.restartServerFailed);
+  }, [t.home.restartServerFailed]);
+
+  return { canRestart, restarting, restartServer };
+}

package/src/app/lib/utils.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { cn } from './utils.ts';
+
+describe('cn', () => {
+  it('joins multiple class names', () => {
+    expect(cn('a', 'b', 'c')).toBe('a b c');
+  });
+
+  it('drops falsy values', () => {
+    expect(cn('a', false, undefined, null, '', 'b')).toBe('a b');
+  });
+
+  it('flattens arrays and conditional objects from clsx', () => {
+    expect(cn(['a', 'b'], { c: true, d: false })).toBe('a b c');
+  });
+
+  it('lets later tailwind classes override earlier ones', () => {
+    expect(cn('p-2', 'p-4')).toBe('p-4');
+    expect(cn('text-red-500', 'text-blue-500')).toBe('text-blue-500');
+  });
+
+  it('preserves classes that target different properties', () => {
+    expect(cn('p-2', 'm-4')).toBe('p-2 m-4');
+  });
+});

package/src/app/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}