diorama-js 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Base error class for all Diorama errors.
+ * Every error has a `code` property for programmatic handling.
+ */
+declare class DioramaError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** GitHub returns 404 for the repository. */
+declare class RepoNotFoundError extends DioramaError {
+    constructor(owner: string, repo: string);
+}
+/** The specified branch doesn't exist. */
+declare class BranchNotFoundError extends DioramaError {
+    constructor(owner: string, repo: string, branch: string);
+}
+/** GitHub API rate limit exceeded. */
+declare class RateLimitError extends DioramaError {
+    readonly resetAt: Date | null;
+    constructor(resetTimestamp?: number);
+}
+/** Fetch failures, CORS issues, timeouts. */
+declare class NetworkError extends DioramaError {
+    constructor(message?: string);
+}
+/** Can't detect a supported project type. */
+declare class ProjectTypeError extends DioramaError {
+    constructor(message?: string);
+}
+/** Project imports a Node.js built-in module. */
+declare class NodeBuiltinError extends DioramaError {
+    readonly moduleName: string;
+    constructor(moduleName: string);
+}
+/** esbuild reports a syntax error during transpilation. */
+declare class TranspileError extends DioramaError {
+    readonly file: string;
+    readonly line?: number;
+    readonly column?: number;
+    constructor(message: string, file: string, line?: number, column?: number);
+}
+/** esbuild-wasm binary fails to download or initialize. */
+declare class TranspilerLoadError extends DioramaError {
+    constructor(message?: string);
+}
+/** HTML assembly hits an unresolvable state. */
+declare class AssemblyError extends DioramaError {
+    constructor(message: string);
+}
+/** A dependency can't be resolved on the CDN. */
+declare class PackageNotFoundError extends DioramaError {
+    readonly packageName: string;
+    constructor(packageName: string);
+}
+/** No index.html or JS entry point found. */
+declare class EntryPointError extends DioramaError {
+    constructor(message?: string);
+}
+
+/** A fully resolved project fetched from GitHub. */
+interface ResolvedProject {
+    owner: string;
+    repo: string;
+    branch: string;
+    /** Git tree SHA — used as cache key. */
+    sha: string;
+    /** Relative path → text file content. */
+    files: Map<string, string>;
+    /** Relative path → binary blob (images, fonts, etc.). */
+    binaryFiles: Map<string, Blob>;
+}
+type ProjectType = 'static' | 'static-esm' | 'jsx' | 'typescript' | 'jsx-typescript' | 'vite';
+type Framework = 'react' | 'preact' | 'solid' | 'none';
+/** Result of project type detection / analysis. */
+interface ProjectConfig {
+    type: ProjectType;
+    /** Path to the main HTML file (may be generated). */
+    entryPoint: string;
+    /** npm dependencies from package.json (name → semver). */
+    dependencies: Record<string, string>;
+    framework: Framework;
+    hasJSX: boolean;
+    hasTypeScript: boolean;
+    /** JS entry point for generated HTML shells (e.g. `src/index.tsx`). */
+    jsEntryPoint?: string;
+    /** Whether the project uses Vite as its build tool. */
+    isVite: boolean;
+}
+type CDNProviderName = 'esm.sh' | 'skypack' | 'unpkg';
+type CacheStrategy = 'normal' | 'aggressive';
+type LoadingStrategy = 'eager' | 'click' | 'viewport';
+/**
+ * Built-in decorative frame styles that wrap the rendered iframe.
+ *
+ * - `'none'`      — No frame (default).
+ * - `'standard'`  — Clean, minimal border with subtle shadow.
+ * - `'polaroid'`  — Polaroid-photo style with thick white bottom.
+ * - `'museum'`    — Ornate golden frame like a fine-art gallery.
+ * - `'terminal'`  — Dark terminal / code-editor chrome.
+ * - `'postcard'`  — Vintage postcard with stamp and postmark.
+ * - `'blueprint'` — Technical blueprint with grid overlay border.
+ * - `'browser'`   — Browser window chrome with address bar.
+ */
+type FrameStyle = 'none' | 'standard' | 'polaroid' | 'museum' | 'terminal' | 'postcard' | 'blueprint' | 'browser';
+interface DioramaOptions {
+    /** Enable localStorage caching. Default: `true`. */
+    cache?: boolean;
+    /** Cache time-to-live in seconds. Default: `3600` (1 hour). */
+    cacheTTL?: number;
+    /** Cache strategy. `'aggressive'` also caches the tree SHA. Default: `'normal'`. */
+    cacheStrategy?: CacheStrategy;
+    /** CDN used to resolve bare npm imports. Default: `'esm.sh'`. */
+    cdnProvider?: CDNProviderName;
+    /** Optional GitHub personal-access token (increases rate limit to 5 000/h). */
+    githubToken?: string;
+    /** URL to the esbuild-wasm binary. `'auto'` loads from esm.sh. */
+    esbuildWasmURL?: string | 'auto';
+    /** Maximum parallel file fetches. Default: `6`. */
+    maxConcurrentFetches?: number;
+    /** Total render timeout in milliseconds. Default: `30000`. */
+    timeout?: number;
+}
+interface RenderOptions {
+    /** Override the branch to render. */
+    branch?: string;
+    /** Render a subdirectory within the repo. */
+    subdirectory?: string;
+    /** When to create and populate the iframe. Default: `'eager'`. */
+    loading?: LoadingStrategy;
+    /** Image URL shown as a placeholder for `click` / `viewport` loading. */
+    placeholder?: string;
+    /** CSS height of the iframe. Default: `'500px'`. */
+    height?: string;
+    /** Decorative frame style wrapping the iframe. Default: `'none'`. */
+    frame?: FrameStyle;
+    /** Allow click-to-expand the preview to fill the viewport. Default: `false`. */
+    expand?: boolean;
+    /** Iframe sandbox flags. Default: `['allow-scripts']`. */
+    sandbox?: string[];
+    /** Override automatic project type detection. */
+    projectType?: ProjectType;
+    /** Override entry point detection. */
+    entryPoint?: string;
+    /** Glob patterns of files to include. */
+    include?: string[];
+    /** Glob patterns of files to exclude. */
+    exclude?: string[];
+    /** Called when rendering completes successfully. */
+    onLoad?: () => void;
+    /** Called when an error occurs at any pipeline stage. */
+    onError?: (error: DioramaError) => void;
+}
+interface DioramaInstance {
+    /** Re-fetch the project and re-render. */
+    reload(): Promise<void>;
+    /** Remove the iframe, revoke Blob URLs, clean up observers. */
+    destroy(): void;
+}
+
+declare class Diorama {
+    private options;
+    private cache;
+    constructor(options?: DioramaOptions);
+    /**
+     * Fetch, transform, and render a GitHub project inside a
+     * sandboxed iframe.
+     *
+     * @param container CSS selector or DOM element.
+     * @param repoURL   GitHub URL or `owner/repo` shorthand.
+     * @param options    Per-render options.
+     * @returns A handle for reloading or destroying the instance.
+     */
+    render(container: string | HTMLElement, repoURL: string, options?: RenderOptions): Promise<DioramaInstance>;
+    /**
+     * Pre-fetch a project (resolve + cache) without rendering.
+     */
+    prefetch(repoURL: string, options?: Pick<RenderOptions, 'branch' | 'subdirectory'>): Promise<void>;
+    /**
+     * Clear cached data.
+     * @param repoSlug Optional `owner/repo` to clear a specific entry.
+     */
+    clearCache(repoSlug?: string): void;
+    private fetchProject;
+}
+
+export { AssemblyError, BranchNotFoundError, type CDNProviderName, type CacheStrategy, Diorama, DioramaError, type DioramaInstance, type DioramaOptions, EntryPointError, type FrameStyle, type Framework, type LoadingStrategy, NetworkError, NodeBuiltinError, PackageNotFoundError, type ProjectConfig, type ProjectType, ProjectTypeError, RateLimitError, type RenderOptions, RepoNotFoundError, type ResolvedProject, TranspileError, TranspilerLoadError };