@illuma-ai/codeviz 1.0.0

package/dist/previewTemplate.d.ts

@@ -0,0 +1,19 @@
+import { ImportMap, PreviewTemplate } from './types';
+
+/**
+ * Generate the srcdoc HTML for the preview iframe.
+ *
+ * For React templates: sets up import map, injects transpiled code as a module,
+ * mounts the default export into #root.
+ *
+ * For HTML templates: renders raw HTML directly.
+ */
+export declare function buildPreviewHtml(options: {
+    transpiledCode: string;
+    template: PreviewTemplate;
+    importMap: ImportMap;
+    tailwindCdn?: string | false;
+    externalResources?: string[];
+    extraFiles?: Record<string, string>;
+}): string;
+//# sourceMappingURL=previewTemplate.d.ts.map

package/dist/previewTemplate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"previewTemplate.d.ts","sourceRoot":"","sources":["../src/previewTemplate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAK1D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,eAAe,CAAC;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC,GAAG,MAAM,CA6CT"}

package/dist/templates.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pre-built starter templates for Ranger's LLM agent.
+ *
+ * KEY DESIGN: Every template includes the FULL dependency preamble (even unused
+ * imports). This means the agent NEVER hits missing-dep errors — it just
+ * uses whatever it needs from the imports already present. Unused imports
+ * are tree-shaken by the browser (never fetched if not used).
+ *
+ * The agent picks a template based on user query, then edits the body.
+ * The preamble + structure stays intact, saving hundreds of tokens.
+ */
+export interface Template {
+    id: string;
+    name: string;
+    description: string;
+    /** Keywords that help the agent pick this template from a user query */
+    keywords: string[];
+    code: string;
+    type: 'react-ts' | 'html' | 'markdown' | 'mermaid' | 'svg' | 'csv' | 'json';
+    language: string;
+}
+export declare const templates: Record<string, Template>;
+/** Get a template by ID */
+export declare function getTemplate(id: string): Template | undefined;
+/** Get all template IDs */
+export declare function getTemplateIds(): string[];
+/**
+ * Returns a summary of all templates for agent system prompts.
+ */
+export declare function getTemplateSummary(): string;
+/**
+ * Pick the best template based on user query keywords.
+ * Returns the template ID, or 'blank' if no strong match.
+ */
+export declare function pickTemplate(query: string): string;
+//# sourceMappingURL=templates.d.ts.map

package/dist/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../src/templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,SAAS,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAyCD,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAiyB9C,CAAC;AAEF,2BAA2B;AAC3B,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAE5D;AAED,2BAA2B;AAC3B,wBAAgB,cAAc,IAAI,MAAM,EAAE,CAEzC;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAI3C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBlD"}

package/dist/transpiler.d.ts

@@ -0,0 +1,25 @@
+import { PreviewError } from './types';
+
+export interface TranspileResult {
+    code: string;
+    error: PreviewError | null;
+}
+/**
+ * Transpile TSX/JSX source code to plain JavaScript using Sucrase.
+ *
+ * Sucrase is ~20x faster than Babel and handles JSX/TypeScript
+ * without a full bundler. The output uses ES module imports which
+ * are resolved by the browser via import maps.
+ *
+ * Returns structured errors with line/column for agent consumption.
+ */
+export declare function transpile(source: string, options?: {
+    filename?: string;
+    isTypeScript?: boolean;
+    isJSX?: boolean;
+}): TranspileResult;
+/**
+ * Transpile multiple files and return a map of filename → transpiled code
+ */
+export declare function transpileFiles(files: Record<string, string>): Record<string, TranspileResult>;
+//# sourceMappingURL=transpiler.d.ts.map

package/dist/transpiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transpiler.d.ts","sourceRoot":"","sources":["../src/transpiler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B;AAID;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC;CACZ,GACL,eAAe,CA0BjB;AAwDD;;GAEG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC5B,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAMjC"}

package/dist/types.d.ts

@@ -0,0 +1,170 @@
+import { editor } from 'monaco-editor';
+
+/** Supported preview template types */
+export type PreviewTemplate = 'react' | 'react-ts' | 'html' | 'markdown' | 'mermaid' | 'svg' | 'csv' | 'json';
+/** Import map structure for the preview iframe */
+export interface ImportMap {
+    imports: Record<string, string>;
+    scopes?: Record<string, Record<string, string>>;
+}
+/** Categories of errors that can occur in the preview */
+export type PreviewErrorCategory = 'transpilation' | 'runtime' | 'import' | 'console-error' | 'unhandled-rejection';
+export type PreviewErrorSeverity = 'error' | 'warning' | 'info';
+/**
+ * Structured error emitted by the preview.
+ *
+ * Designed for AI agent consumption — includes enough context for
+ * the agent to construct a targeted fix prompt.
+ */
+export interface PreviewError {
+    /** Unique ID for deduplication */
+    id: string;
+    /** Error category */
+    category: PreviewErrorCategory;
+    /** Severity level */
+    severity: PreviewErrorSeverity;
+    /** Human-readable error message */
+    message: string;
+    /** Full stack trace if available */
+    stack?: string;
+    /** Line number (1-indexed) */
+    line?: number;
+    /** Column number (1-indexed) */
+    column?: number;
+    /**
+     * Surrounding source lines for context.
+     * Format: "lineNum: content" per line.
+     */
+    sourceContext?: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/** Configuration for the CodeViz component */
+export interface CodeVizProps {
+    /** Initial source code to display */
+    code?: string;
+    /** Language for the editor (tsx, jsx, html, css, etc.) */
+    language?: string;
+    /** Preview template type — determines how code is rendered */
+    template?: PreviewTemplate;
+    /** Template ID from built-in templates (overrides code/language/template) */
+    templateId?: string;
+    /** Custom import map overrides — merged with defaults */
+    importMap?: ImportMap;
+    /** Custom dependencies to add to the import map (package → CDN URL) */
+    dependencies?: Record<string, string>;
+    /** CDN base URL for resolving bare imports (default: https://esm.sh) */
+    cdnBase?: string;
+    /** External resources (CSS/JS URLs) to inject into the preview iframe */
+    externalResources?: string[];
+    /** Tailwind CSS CDN URL — set to false to disable */
+    tailwindCdn?: string | false;
+    /** Called when code changes in the editor */
+    onChange?: (code: string) => void;
+    /** Called when a structured error occurs in the preview */
+    onError?: (error: PreviewError) => void;
+    /** Called when preview finishes loading */
+    onLoad?: () => void;
+    /** Show/hide the editor pane */
+    showEditor?: boolean;
+    /** Show/hide the preview pane */
+    showPreview?: boolean;
+    /** Initial view mode */
+    defaultView?: 'split' | 'code' | 'preview';
+    /** Monaco editor options override */
+    editorOptions?: editor.IStandaloneEditorConstructionOptions;
+    /** Custom class name for the root container */
+    className?: string;
+    /** Height of the component (default: 100%) */
+    height?: string | number;
+    /** Width of the component (default: 100%) */
+    width?: string | number;
+    /** Theme for editor and preview */
+    theme?: 'light' | 'dark';
+    /** Read-only mode — disables editing */
+    readOnly?: boolean;
+    /** Whether to show the loading overlay (default: true) */
+    showLoader?: boolean;
+    /** Custom loader component */
+    loader?: React.ReactNode;
+    /** Show/hide the toolbar (default: true) */
+    showToolbar?: boolean;
+    /** Show/hide the status bar (default: true) */
+    showStatusBar?: boolean;
+    /** Called when the close button is clicked — Ranger can unmount or hide the preview */
+    onClose?: () => void;
+    /** Called when fullscreen state changes */
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+}
+/**
+ * Imperative handle exposed by CodeViz via React.forwardRef.
+ *
+ * This is the primary API for Ranger to control the preview programmatically.
+ * Matches CodeSandboxHandle patterns where applicable.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<CodeVizHandle>(null);
+ *
+ * // Stream code token-by-token during LLM generation
+ * ref.current?.streamCode('export default function App() {');
+ * ref.current?.streamCode('export default function App() {\n  return <h1>Hello</h1>');
+ * ref.current?.commitCode(); // final — triggers preview rebuild
+ *
+ * // Or update entire code at once
+ * ref.current?.setCode(fullCode);
+ *
+ * // Read errors for agent feedback
+ * const errors = ref.current?.getErrors();
+ * ```
+ */
+export interface CodeVizHandle {
+    /** Get current code from the editor */
+    getCode: () => string;
+    /** Set code programmatically (full replace, triggers preview) */
+    setCode: (code: string) => void;
+    /**
+     * Stream partial code to the editor without triggering preview rebuild.
+     * Call this on each LLM token/chunk. The editor updates live but the
+     * preview iframe only rebuilds on commitCode() or after debounce.
+     *
+     * @param code - The full accumulated code so far (not a delta)
+     */
+    streamCode: (code: string) => void;
+    /**
+     * Commit the streamed code — triggers transpilation + preview rebuild.
+     * Call this when the LLM finishes generating.
+     */
+    commitCode: () => void;
+    /** Force refresh the preview iframe */
+    refresh: () => void;
+    /** Switch view mode */
+    setView: (view: 'split' | 'code' | 'preview') => void;
+    /**
+     * Apply a surgical string replacement to the current code.
+     * Returns true if the replacement was found and applied.
+     *
+     * @param oldStr - Exact string to find in the current code
+     * @param newStr - Replacement string
+     */
+    editCode: (oldStr: string, newStr: string) => boolean;
+    /** Get all structured errors */
+    getErrors: () => PreviewError[];
+    /** Clear all errors */
+    clearErrors: () => void;
+    /** Whether the preview is currently loading */
+    isLoading: () => boolean;
+}
+/** Message sent from iframe to parent for error reporting */
+export interface IframeMessage {
+    type: 'codeviz';
+    action: 'ready' | 'error' | 'console';
+    payload?: {
+        message?: string;
+        level?: string;
+        stack?: string;
+        line?: number;
+        column?: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@illuma-ai/codeviz",
+  "version": "1.0.0",
+  "description": "Multi-format code & content preview — Monaco editor, live React/HTML/Markdown/SVG/CSV/JSON rendering, streaming API, zoom/pan, download",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite serve demo",
+    "build": "vite build",
+    "build:demo": "vite build --config vite.demo.config.ts",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "dependencies": {
+    "@monaco-editor/react": "^4.6.0",
+    "monaco-editor": "^0.47.0",
+    "sucrase": "^3.35.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.2.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^5.3.0",
+    "vite": "^5.4.0",
+    "vite-plugin-css-injected-by-js": "^3.5.0",
+    "vite-plugin-dts": "^3.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/illuma-ai/codeviz"
+  },
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "preview",
+    "monaco",
+    "editor",
+    "codeviz",
+    "artifact",
+    "sandbox",
+    "markdown",
+    "mermaid",
+    "svg",
+    "csv",
+    "json",
+    "streaming",
+    "llm"
+  ]
+}