@qds.dev/code 0.8.5 → 0.9.7

package/README.md

@@ -0,0 +1,102 @@
+# @qds.dev/code
+
+**Interactive code previews and playgrounds for Qwik**
+
+[![npm version](https://img.shields.io/npm/v/@qds.dev/code.svg)](https://www.npmjs.com/package/@qds.dev/code)
+
+## Overview
+
+Documentation with static code examples is hard to learn from. You want to experiment, modify, and see results immediately, but building a live code playground is complex. You need sandboxed execution, bundling, and preview rendering.
+
+**@qds.dev/code** provides a PreviewCompiler class that bundles and executes Qwik code in the browser. Powered by Rolldown WASM for fast bundling, your users can compile code and see instant results without any server setup.
+
+**What makes this different:** Incremental builds. WASM-based bundling for instant feedback. No remote compilation, no cold starts, no server costs.
+
+## Installation
+
+```bash
+npm install @qds.dev/code
+```
+
+**Note:** Typically used in documentation sites, not application code. The WASM bundler adds significant weight (~2MB+). It's recommended to only show the component preview when the user has made the intent they would like to edit code or view a preview.
+
+## Quick Start
+
+**Simplest case:** Compile and run code
+
+```typescript
+import { PreviewCompiler } from '@qds.dev/code/preview';
+import { component$ } from '@qwik.dev/core';
+
+export default component$(() => {
+  const compiler = new PreviewCompiler({
+    deps: {
+      '@qwik.dev/core': './path-to-core-module'
+    }
+  });
+
+  const result = await compiler.compile({
+    srcInputs: {
+      '/src/app.tsx': `export default component$(() => {
+        return <button>Click me</button>;
+      });`
+    }
+  });
+
+  return <div>{/* Render result */}</div>;
+});
+```
+
+**Common pattern:** Browser-based bundling
+
+```typescript
+import { PreviewCompiler } from '@qds.dev/code/preview';
+
+export default component$(() => {
+  const compiler = new PreviewCompiler({
+    deps: {
+      '@qwik.dev/core': './path-to-core-module'
+    }
+  });
+
+  const compile$ = $(async (code: string) => {
+    return await compiler.compile({
+      srcInputs: { '/src/app.tsx': code }
+    });
+  });
+
+  return <div>{/* Use compile$ for interactive editing */}</div>;
+});
+```
+
+## Architecture
+
+For package internals, dependency relationships, and design decisions, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `.` | debug function for development logging |
+| `./preview` | PreviewCompiler class and compilation utilities |
+| `./preview/node` | Server-side helpers for REPL |
+
+## Why This Pattern?
+
+**Browser-based bundling:** We use Rolldown WASM instead of server-side compilation because it eliminates network latency and server costs. Your users get instant feedback. No waiting for compilation, no server to configure or maintain.
+
+**Component isolation:** Previews run in sandboxed iframes, isolated from your main application. This prevents code in previews from affecting your documentation site's state or styles. Users can experiment freely without breaking anything.
+
+## Related Packages
+
+**Depends on:**
+- [@rolldown/browser](https://www.npmjs.com/package/@rolldown/browser) - WASM bundler for in-browser compilation
+
+**Used by:**
+- QDS documentation site - Powers all interactive code examples
+
+## Known Limitations
+
+- **Bundle size:** The WASM bundler adds significant weight (~2MB+ for Rolldown). This package is designed for documentation sites where rich interactivity justifies the cost, not for production applications.
+- **Documentation only:** Not intended for production apps. The bundle size and browser-based compilation are optimized for learning environments.
+- **Modern browsers:** Requires WebAssembly and modern JavaScript features (ES2020+). Won't work in IE11 or older browsers.

package/lib-types/src/debug.d.ts

@@ -0,0 +1 @@
+export declare function debug(...args: unknown[]): void;

package/lib-types/src/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./debug";
+export * from "./preview";

package/lib-types/src/preview/bundler/bundled-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared configuration for bundled Qwik dependencies.
+ * This defines which files from @qwik.dev/core should be bundled.
+ *
+ * Both the library (using ?inline-asset) and docs (using ?no-transform)
+ * use this same configuration to ensure consistency.
+ */
+import type { PkgUrls } from "../types";
+export declare const QWIK_PKG_NAME = "@qwik.dev/core";
+/**
+ * List of file paths within @qwik.dev/core that need to be bundled
+ */
+export declare const BUNDLED_FILE_PATHS: readonly ["/dist/build/index.d.ts", "/dist/core.d.ts", "/dist/core.min.mjs", "/dist/core.mjs", "/dist/optimizer.mjs", "/dist/server.mjs", "/dist/server.d.ts", "/dist/preloader.mjs", "/dist/qwikloader.js", "/bindings/qwik.wasm.mjs", "/bindings/qwik_wasm_bg.wasm", "/handlers.mjs"];
+/**
+ * Map of internal path aliases to actual file paths
+ * Some internal references use core.d.ts but the actual file is core-internal.d.ts
+ */
+export declare const FILE_PATH_ALIASES: Record<string, string>;
+/**
+ * Get the actual file path to import, considering aliases
+ */
+export declare function getImportPath(path: string): string;
+/**
+ * Helper to create a bundled object from imported assets.
+ * This ensures both files use the same structure without duplication.
+ *
+ * The imports array must be in the same order as BUNDLED_FILE_PATHS.
+ *
+ * @param imports - Array of imported content (string URLs or inline content) in BUNDLED_FILE_PATHS order
+ * @param version - The Qwik version
+ * @returns A properly structured PkgUrls object
+ */
+export declare function createBundledConfig(imports: readonly string[], version: string): PkgUrls;

package/lib-types/src/preview/bundler/bundled.d.ts

@@ -0,0 +1,3 @@
+import type { PkgUrls } from "../types";
+export declare const bundled: PkgUrls;
+export declare const getDeps: () => PkgUrls;

package/lib-types/src/preview/bundler/bundled.unit.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/bundler/client-events-listener.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/bundler/index.d.ts

@@ -0,0 +1,34 @@
+/** Bundler that manages WebWorkers */
+import type { PkgUrls, PreviewInputOptions, PreviewResult } from "../types";
+import type { OutgoingMessage } from "./repl-bundler-worker";
+declare class Bundler {
+    worker: Worker | null;
+    private initP;
+    private ready;
+    private deps;
+    private qwikWasm?;
+    private timer;
+    buildPromises: Map<number, {
+        resolve: (value: PreviewResult) => void;
+        reject: (reason?: any) => void;
+    }>;
+    nextBuildId: number;
+    constructor(deps: PkgUrls, qwikWasm?: WebAssembly.Module);
+    initWorker(): void;
+    messageHandler: (e: MessageEvent<OutgoingMessage>) => void;
+    keepAlive(): void;
+    bundle(options: Omit<PreviewInputOptions, "version" | "serverUrl">): Promise<PreviewResult>;
+    terminateWorker(): void;
+    private _ssrWorker;
+    private _ssrWorkerP;
+    private _ssrKey;
+    private _resultResolver;
+    private getSsrWorker;
+    executeSSR(result: PreviewResult): Promise<{
+        html: string;
+        events?: any[];
+    }>;
+    hasQwikWasm(): boolean;
+}
+export declare const getBundler: (deps?: PkgUrls, qwikWasm?: WebAssembly.Module) => Bundler;
+export {};

package/lib-types/src/preview/bundler/repl-bundler-worker.d.ts

@@ -0,0 +1,30 @@
+import type { PkgUrls, ReplInputOptions, ReplResult } from "../types";
+interface MessageBase {
+    type: string;
+}
+export interface InitMessage extends MessageBase {
+    type: "init";
+    deps: PkgUrls;
+    qwikWasm?: WebAssembly.Module;
+}
+export interface BundleMessage extends MessageBase {
+    type: "bundle";
+    buildId: number;
+    data: Omit<ReplInputOptions, "version" | "serverUrl">;
+}
+export interface ReadyMessage extends MessageBase {
+    type: "ready";
+}
+export interface ResultMessage extends MessageBase {
+    type: "result";
+    buildId: number;
+    result: ReplResult;
+}
+export interface ErrorMessage extends MessageBase {
+    type: "error";
+    buildId: number;
+    error: string;
+    stack?: string;
+}
+export type OutgoingMessage = ReadyMessage | ResultMessage | ErrorMessage;
+export {};

package/lib-types/src/preview/bundler/repl-ssr-worker.d.ts

@@ -0,0 +1,27 @@
+import type { QwikManifest } from "@qwik.dev/core/optimizer";
+import type { PreviewEvent } from "../types";
+interface MessageBase {
+    type: string;
+}
+export interface InitSSRMessage extends MessageBase {
+    type: "run-ssr";
+    replId: string;
+    entry: string;
+    baseUrl: string;
+    manifest: QwikManifest | undefined;
+}
+export interface SSRReadyMessage extends MessageBase {
+    type: "ready";
+}
+export interface SSRResultMessage extends MessageBase {
+    type: "ssr-result";
+    html: string;
+    events: PreviewEvent[];
+}
+export interface SSRErrorMessage extends MessageBase {
+    type: "ssr-error";
+    error: string;
+    stack?: string;
+}
+export type OutgoingMessage = SSRReadyMessage | SSRResultMessage | SSRErrorMessage;
+export {};

package/lib-types/src/preview/bundler/rollup-plugins.d.ts

@@ -0,0 +1,5 @@
+import type { Plugin } from "@rolldown/browser";
+import type { PkgUrls, PreviewInputOptions } from "../types";
+export declare const definesPlugin: (defines: Record<string, string>) => Plugin;
+export declare const replResolver: (deps: PkgUrls, options: Pick<PreviewInputOptions, "srcInputs" | "buildMode">, target: "client" | "ssr") => Plugin;
+export declare const replCss: (options: Pick<PreviewInputOptions, "srcInputs">) => Plugin;

package/lib-types/src/preview/bundler/rollup-plugins.unit.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const QWIK_PKG_NAME = "@qwik.dev/core";
+export declare const PREVIEW_CONFIG: {
+    serviceWorkerPath: string;
+    scope: string;
+};

package/lib-types/src/preview/index.d.ts

@@ -0,0 +1,19 @@
+import type { PkgUrls, PreviewInputOptions, PreviewResult } from "./types";
+export * from "./bundler";
+export { BUNDLED_FILE_PATHS, createBundledConfig, FILE_PATH_ALIASES, getImportPath, QWIK_PKG_NAME } from "./bundler/bundled-config";
+export * from "./constants";
+export * from "./repl-helpers";
+export * from "./register-preview-sw";
+export type { PkgUrls, PreviewInputOptions, PreviewInputOptions as ReplInputOptions, PreviewModuleInput, PreviewModuleInput as ReplModuleInput, PreviewModuleOutput, PreviewModuleOutput as ReplModuleOutput, PreviewResult, PreviewResult as ReplResult } from "./types";
+export * from "./types";
+export interface PreviewCompilerOptions extends Partial<PreviewInputOptions> {
+    /** Qwik dependency URLs - must be provided by consuming app */
+    deps: PkgUrls;
+}
+export declare class PreviewCompiler {
+    options: PreviewCompilerOptions;
+    private bundler;
+    constructor(options: PreviewCompilerOptions);
+    compile(input: Partial<PreviewInputOptions>): Promise<PreviewResult>;
+}
+export { PreviewCompiler as ReplCompiler };

package/lib-types/src/preview/mocks/browser.d.ts

@@ -0,0 +1,2 @@
+export declare const handlers: import("msw").HttpHandler[];
+export declare const worker: import("msw/browser").SetupWorker;

package/lib-types/src/preview/preview-sw.d.ts

@@ -0,0 +1,20 @@
+export type RequestMessage = {
+    type: "preview-request";
+    requestId: number;
+    previewId: string;
+    url: string;
+};
+export type ResponseMessage = {
+    type: "preview-response";
+    requestId: number;
+    response: {
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: string;
+    } | null;
+};
+type SendPreviewMessage = (msg: RequestMessage) => void;
+/** Intercept requests for `/repl/[id]/*` and request them over the broadcast channel */
+export declare const handleFetch: (ev: FetchEvent, selfOrigin: string, sendMessage: SendPreviewMessage) => void;
+export {};

package/lib-types/src/preview/preview-sw.unit.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/register-preview-sw.d.ts

@@ -0,0 +1,2 @@
+export declare const registerReplSW: () => Promise<ServiceWorkerRegistration | null>;
+export declare const _resetPromise: () => void;

package/lib-types/src/preview/register-preview-sw.unit.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/repl-editor.d.ts

@@ -0,0 +1 @@
+export declare const ReplEditor: import("@qwik.dev/core").Component<unknown>;

package/lib-types/src/preview/repl-helpers-node.d.ts

@@ -0,0 +1,4 @@
+export interface CopyReplAssetsOptions {
+    publicDir: string;
+}
+export declare const copyReplAssets: ({ publicDir }: CopyReplAssetsOptions) => Promise<void>;

package/lib-types/src/preview/repl-helpers.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin } from "vite";
+export type ReplWorkerMode = "dev" | "preview";
+export interface ReplWorkerUrlOptions {
+    mode: ReplWorkerMode;
+    scopePrefix?: string;
+}
+export declare const getReplWorkerUrls: ({ mode, scopePrefix }: ReplWorkerUrlOptions) => {
+    bundler: string;
+    ssr: string;
+};
+export interface ReplVitePluginOptions {
+    serviceWorkerScope?: string;
+    assetsInlineLimit?: number;
+    optimizeDepsExclude?: string[];
+}
+export declare const getReplVitePlugin: (options?: ReplVitePluginOptions) => Plugin;

package/lib-types/src/preview/repl-helpers.unit.d.ts

@@ -0,0 +1 @@
+export {};

package/lib-types/src/preview/test-extend.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extended test with MSW worker fixture.
+ * - Starts MSW before each test
+ * - Exposes `worker` in test context for adding handlers
+ * - Resets handlers after each test
+ */
+export declare const test: import("vitest").TestAPI<{
+    worker: import("msw/browser").SetupWorker;
+}>;

package/lib-types/src/preview/types.d.ts

@@ -0,0 +1,70 @@
+import type { Signal } from "@qwik.dev/core";
+import type { Diagnostic, QwikManifest, QwikRollupPluginOptions, TransformModule } from "@qwik.dev/core/optimizer";
+export interface PreviewAppInput {
+    files: PreviewModuleInput[];
+    version: string;
+    buildMode: "development" | "production";
+    entryStrategy: string;
+    debug?: boolean;
+}
+export type PkgUrls = {
+    [pkgName: string]: {
+        [path: string]: string;
+        version: string;
+    };
+};
+export interface PreviewInputOptions extends Omit<QwikRollupPluginOptions, "srcDir"> {
+    replId: string;
+    srcInputs: PreviewModuleInput[];
+    version: string;
+    buildMode: "development" | "production";
+    debug?: boolean;
+    qwikWasm?: WebAssembly.Module;
+}
+export interface PreviewModuleInput {
+    path: string;
+    code: string;
+    hidden?: boolean;
+}
+export interface PreviewModuleOutput {
+    path: string;
+    code: string;
+    size?: string;
+    shorten?: Signal<boolean>;
+}
+export interface PreviewEvent {
+    start: number;
+    end?: number;
+    kind: "console-log" | "console-debug" | "console-warn" | "console-error" | "symbol" | "pause" | "resume" | "client-module" | "prefetch";
+    scope: "ssr" | "client" | "build" | "network";
+    message: string[];
+    element?: Element;
+}
+export interface PreviewResult {
+    buildId: number;
+    replId: string;
+    html: string;
+    transformedModules: TransformModule[];
+    clientBundles: PreviewModuleOutput[];
+    ssrModules: PreviewModuleOutput[];
+    manifest: QwikManifest | undefined;
+    diagnostics: Diagnostic[];
+    events: PreviewEvent[];
+}
+export type SSROutgoingMessage = {
+    type: "ready";
+} | {
+    type: "ssr-result";
+    html: string;
+    events: any[];
+} | {
+    type: "ssr-error";
+    error: string;
+    stack?: string;
+};
+export type ReplAppInput = PreviewAppInput;
+export type ReplInputOptions = PreviewInputOptions;
+export type ReplModuleInput = PreviewModuleInput;
+export type ReplModuleOutput = PreviewModuleOutput;
+export type ReplEvent = PreviewEvent;
+export type ReplResult = PreviewResult;