npm - round-core - Versions diffs - 0.0.5 → 0.0.6 - Mend

round-core 0.0.5 → 0.0.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md +2 -2
package/dist/cli.js +49 -0
package/dist/index.d.ts +326 -0
package/dist/vite-plugin.js +0 -31
package/package.json +2 -1
package/src/cli.js +53 -0
package/src/compiler/vite-plugin.js +0 -35
package/src/index.d.ts +326 -0
package/src/runtime/context.js +12 -0
package/src/runtime/dom.js +10 -0
package/src/runtime/router.js +28 -0
package/src/runtime/signals.js +38 -0
package/src/runtime/store.js +7 -0
package/vite.config.build.js +12 -0

package/README.md CHANGED Viewed

@@ -16,7 +16,7 @@
 npm install round-core
 ```
-Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives (**signals**). This keeps rendering predictable, small, and fast for interactive apps.
+Instead of a Virtual DOM diff, Round updates the UI by subscribing DOM updates directly to reactive primitives (**signals**) and **bindables**. This keeps rendering predictable, small, and fast for interactive apps.
 ## What Round is focused on
@@ -93,7 +93,7 @@ This scaffolds a minimal Round app with `src/app.round` and an example `src/coun
 ## `.round` files
-A `.round` file is a JSX-based component module (ESM) compiled by the Round toolchain.
+A `.round` file is a JSX-based component module (ESM) compiled by the Round toolchain. you can also use .jsx files but you wont get the round JSX superset features like conditional rendering and other features.
 Example `src/app.round`:

package/dist/cli.js CHANGED Viewed

@@ -10,6 +10,19 @@ function onSignal() {
 }
 process.on("SIGINT", onSignal);
 process.on("SIGTERM", onSignal);
+process.on("exit", () => {
+  cleanupTemporaryFiles();
+});
+const temporaryFiles = /* @__PURE__ */ new Set();
+function cleanupTemporaryFiles() {
+  for (const f of temporaryFiles) {
+    try {
+      if (fs.existsSync(f)) fs.unlinkSync(f);
+    } catch {
+    }
+  }
+  temporaryFiles.clear();
+}
 function normalizePath(p) {
   return p.replaceAll("\\", "/");
 }
@@ -323,6 +336,40 @@ function coerceNumber(v, fallback) {
   const n = Number(v);
   return Number.isFinite(n) ? n : fallback;
 }
+function generateIndexHtml(config) {
+  const name = config?.name ?? "Round";
+  const rawEntry = config?.entry ?? "./src/app.round";
+  let entry = rawEntry;
+  if (entry.startsWith("./")) entry = entry.slice(1);
+  if (!entry.startsWith("/")) entry = "/" + entry;
+  return [
+    "<!DOCTYPE html>",
+    '<html lang="en">',
+    "<head>",
+    '    <meta charset="UTF-8" />',
+    '    <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+    `    <title>${name}</title>`,
+    "</head>",
+    "<body>",
+    '    <div id="app"></div>',
+    '    <script type="module">',
+    "        import { render } from 'round-core';",
+    `        import App from '${entry}';`,
+    "",
+    "        render(App, document.getElementById('app'));",
+    "    <\/script>",
+    "</body>",
+    "</html>"
+  ].join("\n");
+}
+function writeTemporaryIndex(rootDir, config) {
+  const indexPath = path.resolve(rootDir, "index.html");
+  if (fs.existsSync(indexPath)) return false;
+  const content = generateIndexHtml(config);
+  fs.writeFileSync(indexPath, content, "utf8");
+  temporaryFiles.add(indexPath);
+  return true;
+}
 async function runDev({ rootDir, configPathAbs, config }) {
   const startedAt = Date.now();
   const configDir = path.dirname(configPathAbs);
@@ -344,6 +391,7 @@ async function runDev({ rootDir, configPathAbs, config }) {
     const serverPort2 = coerceNumber(nextConfig?.dev?.port, 5173);
     const open2 = Boolean(nextConfig?.dev?.open);
     const base2 = nextConfig?.routing?.base ?? "/";
+    writeTemporaryIndex(rootDir, nextConfig);
     if (showBanner) {
       banner();
       process.stdout.write(`${c("  Config", "gray")}  ${configPathAbs}
@@ -413,6 +461,7 @@ async function runBuild({ rootDir, configPathAbs, config }) {
   normalizePath(path.relative(rootDir, entryAbs));
   const outDir = config?.output ? resolveFrom(configDir, config.output) : resolveFrom(rootDir, "./dist");
   const base = config?.routing?.base ?? "/";
+  writeTemporaryIndex(rootDir, config);
   banner();
   process.stdout.write(`${c("  Config", "gray")}  ${configPathAbs}
 `);

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,326 @@
+/**
+ * Round Framework Type Definitions
+ */
+export interface RoundSignal<T> {
+    /**
+     * Get or set the current value.
+     */
+    (newValue?: T): T;
+    /**
+     * Get the current value (reactive).
+     */
+    value: T;
+    /**
+     * Get the current value without tracking dependencies.
+     */
+    peek(): T;
+    /**
+     * Creates a transformed view of this signal.
+     */
+    transform<U>(fromInput: (v: U) => T, toOutput: (v: T) => U): RoundSignal<U>;
+    /**
+     * Attaches validation logic to the signal.
+     */
+    validate(validator: (next: T, prev: T) => string | boolean | undefined | null, options?: {
+        /** Timing of validation: 'input' (default) or 'blur'. */
+        validateOn?: 'input' | 'blur';
+        /** Whether to run validation immediately on startup. */
+        validateInitial?: boolean;
+    }): RoundSignal<T> & {
+        /** Signal containing the current validation error message. */
+        error: RoundSignal<string | null>;
+        /** Manually trigger validation check. Returns true if valid. */
+        check(): boolean
+    };
+    /**
+     * Creates a read/write view of a specific property path.
+     */
+    $pick<K extends keyof T>(path: K): RoundSignal<T[K]>;
+    $pick(path: string | string[]): RoundSignal<any>;
+    /**
+     * Internal: marks the signal as bindable for two-way bindings.
+     */
+    bind?: boolean;
+}
+/**
+ * Creates a reactive signal.
+ */
+export function signal<T>(initialValue?: T): RoundSignal<T>;
+/**
+ * Creates a bindable signal intended for two-way DOM bindings.
+ */
+export function bindable<T>(initialValue?: T): RoundSignal<T>;
+/**
+ * Run a function without tracking any signals it reads.
+ * Any signals accessed inside the function will not become dependencies of the current effect.
+ */
+export function untrack<T>(fn: () => T): T;
+/**
+ * Create a reactive side-effect that runs whenever its signal dependencies change.
+ */
+export function effect(fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+/**
+ * Create a reactive side-effect with explicit dependencies.
+ */
+export function effect(deps: any[], fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+/**
+ * Create a read-only computed signal derived from other signals.
+ */
+export function derive<T>(fn: () => T): () => T;
+/**
+ * Create a read/write view of a specific path within a signal object.
+ */
+export function pick<T = any>(root: RoundSignal<any>, path: string | string[]): RoundSignal<T>;
+/**
+ * Store API
+ */
+export interface RoundStore<T> {
+    /**
+     * Access a specific key from the store as a bindable signal.
+     */
+    use<K extends keyof T>(key: K): RoundSignal<T[K]>;
+    /**
+     * Update a specific key in the store.
+     */
+    set<K extends keyof T>(key: K, value: T[K]): T[K];
+    /**
+     * Batch update multiple keys in the store.
+     */
+    patch(obj: Partial<T>): void;
+    /**
+     * Get a snapshot of the current state.
+     */
+    snapshot(options?: {
+        /** If true, the returned values will be reactive signals. */
+        reactive?: boolean
+    }): T;
+    /**
+     * Enable persistence for the store.
+     */
+    persist(storageKey: string, options?: {
+        /** The storage implementation (defaults to localStorage). */
+        storage?: Storage;
+        /** Debounce time in milliseconds for writes. */
+        debounce?: number;
+        /** Array of keys to exclude from persistence. */
+        exclude?: string[];
+    }): RoundStore<T>;
+    /**
+     * Action methods defined during store creation.
+     */
+    actions: Record<string, Function>;
+}
+/**
+ * Create a shared global state store with actions and optional persistence.
+ */
+export function createStore<T, A extends Record<string, (state: T, ...args: any[]) => Partial<T> | void>>(
+    initialState: T,
+    actions?: A
+): RoundStore<T> & { [K in keyof A]: (...args: Parameters<A[K]> extends [any, ...infer P] ? P : never) => any };
+/**
+ * Router API
+ */
+export interface RouteProps {
+    /** The path to match. Must start with a forward slash. */
+    route?: string;
+    /** If true, only matches if the path is exactly the same. */
+    exact?: boolean;
+    /** Page title to set in the document header when active. */
+    title?: string;
+    /** Meta description to set in the document header when active. */
+    description?: string;
+    /** Advanced head configuration including links and meta tags. */
+    head?: any;
+    /** Fragment or elements to render when matched. */
+    children?: any;
+}
+/**
+ * Define a route that renders its children when the path matches.
+ */
+export function Route(props: RouteProps): any;
+/**
+ * An alias for Route, typically used for top-level pages.
+ */
+export function Page(props: RouteProps): any;
+export interface LinkProps {
+    /** The destination path. */
+    href: string;
+    /** Alias for href. */
+    to?: string;
+    /** Use SPA navigation (prevents full page reloads). Defaults to true. */
+    spa?: boolean;
+    /** Force a full page reload on navigation. */
+    reload?: boolean;
+    /** Custom click event handler. */
+    onClick?: (e: MouseEvent) => void;
+    /** Link content (text or elements). */
+    children?: any;
+    [key: string]: any;
+}
+/**
+ * A standard link component that performs SPA navigation.
+ */
+export function Link(props: LinkProps): any;
+/**
+ * Define a fallback component or content for when no routes match.
+ */
+export function NotFound(props: {
+    /** Optional component to render for the 404 state. */
+    component?: any;
+    /** Fallback content. ignored if 'component' is provided. */
+    children?: any
+}): any;
+/**
+ * Navigate to a different path programmatically.
+ */
+export function navigate(to: string, options?: {
+    /** If true, replaces the current history entry instead of pushing. */
+    replace?: boolean
+}): void;
+/**
+ * Hook to get a reactive function returning the current normalized pathname.
+ */
+export function usePathname(): () => string;
+/**
+ * Get the current normalized pathname.
+ */
+export function getPathname(): string;
+/**
+ * Hook to get a reactive function returning the current location object.
+ */
+export function useLocation(): () => { pathname: string; search: string; hash: string };
+/**
+ * Get the current location object (pathname, search, hash).
+ */
+export function getLocation(): { pathname: string; search: string; hash: string };
+/**
+ * Hook to get a reactive function returning whether the current path has no matches.
+ */
+export function useIsNotFound(): () => boolean;
+/**
+ * Get whether the current path is NOT matched by any defined route.
+ */
+export function getIsNotFound(): boolean;
+/**
+ * DOM & Context API
+ */
+/**
+ * Create a DOM element or instance a component.
+ */
+export function createElement(tag: any, props?: any, ...children: any[]): any;
+/**
+ * A grouping component that returns its children without a wrapper element.
+ */
+export function Fragment(props: { children?: any }): any;
+export interface Context<T> {
+    /** Internal identifier for the context. */
+    id: number;
+    /** Default value used when no Provider is found in the tree. */
+    defaultValue: T;
+    /** Component that provides a value to all its descendants. */
+    Provider: (props: { value: T; children?: any }) => any;
+}
+/**
+ * Create a new Context object for sharing state between components.
+ */
+export function createContext<T>(defaultValue?: T): Context<T>;
+/**
+ * Read the current value of a context from the component tree.
+ */
+export function readContext<T>(ctx: Context<T>): T;
+/**
+ * Returns a reactive function that reads the current context value.
+ */
+export function bindContext<T>(ctx: Context<T>): () => T;
+/**
+ * Async & Code Splitting
+ */
+/**
+ * Mark a component for lazy loading (code-splitting).
+ * Expects a function returning a dynamic import promise.
+ */
+export function lazy<T>(fn: () => Promise<{ default: T }>): T;
+export interface SuspenseProps {
+    /** Content to show while children (e.g. lazy components) are loading. */
+    fallback: any;
+    /** Content that might trigger a loading state. */
+    children?: any;
+}
+/**
+ * Component that boundaries async operations and renders a fallback while loading.
+ */
+export function Suspense(props: SuspenseProps): any;
+/**
+ * Head Management
+ */
+/**
+ * Define static head metadata (titles, meta tags, favicons, etc.).
+ */
+export function startHead(head: any): any;
+/**
+ * Markdown
+ */
+/**
+ * Component that renders Markdown content into HTML.
+ */
+export function Markdown(props: {
+    /** The markdown string or a function returning it. */
+    content: string | (() => string);
+    /** Remark/Rehype configuration options. */
+    options?: any
+}): any;

package/dist/vite-plugin.js CHANGED Viewed

@@ -614,40 +614,9 @@ ${head.raw}`;
       };
     },
     resolveId(id) {
-      if (id === "/index.html" || id === "index.html") {
-        const fullPath = path.resolve(state.rootDir, "index.html");
-        if (!fs.existsSync(fullPath)) {
-          return "/index.html";
-        }
-      }
       return null;
     },
     load(id) {
-      if (id === "/index.html" || id === "index.html") {
-        const fullPath = path.resolve(state.rootDir, "index.html");
-        if (fs.existsSync(fullPath)) return null;
-        const entry = state.entryRel ?? "./src/index.js";
-        const entryPath = entry.startsWith("/") ? entry : `/${entry}`;
-        return [
-          "<!DOCTYPE html>",
-          '<html lang="en">',
-          "<head>",
-          '    <meta charset="UTF-8" />',
-          '    <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
-          `    <title>${state.name}</title>`,
-          "</head>",
-          "<body>",
-          '    <div id="app"></div>',
-          '    <script type="module">',
-          "        import { render } from 'round-core';",
-          `        import App from '${entryPath}';`,
-          "",
-          "        render(App, document.getElementById('app'));",
-          "    <\/script>",
-          "</body>",
-          "</html>"
-        ].join("\n");
-      }
       if (!isMdRawRequest(id)) return;
       const fileAbs = stripQuery(id);
       try {

package/package.json CHANGED Viewed

@@ -1,8 +1,9 @@
 {
     "name": "round-core",
-    "version": "0.0.5",
+    "version": "0.0.6",
     "description": "A lightweight frontend framework for SPA with signals and fine grained reactivity",
     "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
     "exports": {
         ".": "./dist/index.js",
         "./vite-plugin": "./dist/vite-plugin.js"

package/src/cli.js CHANGED Viewed

@@ -12,6 +12,17 @@ function onSignal() {
 }
 process.on('SIGINT', onSignal);
 process.on('SIGTERM', onSignal);
+process.on('exit', () => {
+    cleanupTemporaryFiles();
+});
+const temporaryFiles = new Set();
+function cleanupTemporaryFiles() {
+    for (const f of temporaryFiles) {
+        try { if (fs.existsSync(f)) fs.unlinkSync(f); } catch { }
+    }
+    temporaryFiles.clear();
+}
 function normalizePath(p) {
     return p.replaceAll('\\', '/');
@@ -330,6 +341,44 @@ function coerceNumber(v, fallback) {
     return Number.isFinite(n) ? n : fallback;
 }
+function generateIndexHtml(config) {
+    const name = config?.name ?? 'Round';
+    const rawEntry = config?.entry ?? './src/app.round';
+    let entry = rawEntry;
+    if (entry.startsWith('./')) entry = entry.slice(1);
+    if (!entry.startsWith('/')) entry = '/' + entry;
+    return [
+        '<!DOCTYPE html>',
+        '<html lang="en">',
+        '<head>',
+        '    <meta charset="UTF-8" />',
+        '    <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
+        `    <title>${name}</title>`,
+        '</head>',
+        '<body>',
+        '    <div id="app"></div>',
+        '    <script type="module">',
+        "        import { render } from 'round-core';",
+        `        import App from '${entry}';`,
+        '',
+        "        render(App, document.getElementById('app'));",
+        '    </script>',
+        '</body>',
+        '</html>'
+    ].join('\n');
+}
+function writeTemporaryIndex(rootDir, config) {
+    const indexPath = path.resolve(rootDir, 'index.html');
+    if (fs.existsSync(indexPath)) return false;
+    const content = generateIndexHtml(config);
+    fs.writeFileSync(indexPath, content, 'utf8');
+    temporaryFiles.add(indexPath);
+    return true;
+}
 async function runDev({ rootDir, configPathAbs, config }) {
     const startedAt = Date.now();
     const configDir = path.dirname(configPathAbs);
@@ -357,6 +406,8 @@ async function runDev({ rootDir, configPathAbs, config }) {
         const open2 = Boolean(nextConfig?.dev?.open);
         const base2 = nextConfig?.routing?.base ?? '/';
+        const isTemp = writeTemporaryIndex(rootDir, nextConfig);
         if (showBanner) {
             banner('Dev Server');
             process.stdout.write(`${c('  Config', 'gray')}  ${configPathAbs}\n`);
@@ -430,6 +481,8 @@ async function runBuild({ rootDir, configPathAbs, config }) {
     const outDir = config?.output ? resolveFrom(configDir, config.output) : resolveFrom(rootDir, './dist');
     const base = config?.routing?.base ?? '/';
+    const isTemp = writeTemporaryIndex(rootDir, config);
     banner('Build');
     process.stdout.write(`${c('  Config', 'gray')}  ${configPathAbs}\n`);
     process.stdout.write(`${c('  OutDir', 'gray')}  ${outDir}\n`);

package/src/compiler/vite-plugin.js CHANGED Viewed

@@ -329,44 +329,9 @@ export default function RoundPlugin(pluginOptions = {}) {
         },
         resolveId(id) {
-            if (id === '/index.html' || id === 'index.html') {
-                const fullPath = path.resolve(state.rootDir, 'index.html');
-                if (!fs.existsSync(fullPath)) {
-                    return '/index.html'; // Virtual ID
-                }
-            }
             return null;
         },
         load(id) {
-            if (id === '/index.html' || id === 'index.html') {
-                const fullPath = path.resolve(state.rootDir, 'index.html');
-                if (fs.existsSync(fullPath)) return null; // Fallback to disk
-                const entry = state.entryRel ?? './src/index.js';
-                const entryPath = entry.startsWith('/') ? entry : `/${entry}`;
-                return [
-                    '<!DOCTYPE html>',
-                    '<html lang="en">',
-                    '<head>',
-                    '    <meta charset="UTF-8" />',
-                    '    <meta name="viewport" content="width=device-width, initial-scale=1.0" />',
-                    `    <title>${state.name}</title>`,
-                    '</head>',
-                    '<body>',
-                    '    <div id="app"></div>',
-                    '    <script type="module">',
-                    "        import { render } from 'round-core';",
-                    `        import App from '${entryPath}';`,
-                    '',
-                    "        render(App, document.getElementById('app'));",
-                    '    </script>',
-                    '</body>',
-                    '</html>'
-                ].join('\n');
-            }
             if (!isMdRawRequest(id)) return;
             const fileAbs = stripQuery(id);

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,326 @@
+/**
+ * Round Framework Type Definitions
+ */
+export interface RoundSignal<T> {
+    /**
+     * Get or set the current value.
+     */
+    (newValue?: T): T;
+    /**
+     * Get the current value (reactive).
+     */
+    value: T;
+    /**
+     * Get the current value without tracking dependencies.
+     */
+    peek(): T;
+    /**
+     * Creates a transformed view of this signal.
+     */
+    transform<U>(fromInput: (v: U) => T, toOutput: (v: T) => U): RoundSignal<U>;
+    /**
+     * Attaches validation logic to the signal.
+     */
+    validate(validator: (next: T, prev: T) => string | boolean | undefined | null, options?: {
+        /** Timing of validation: 'input' (default) or 'blur'. */
+        validateOn?: 'input' | 'blur';
+        /** Whether to run validation immediately on startup. */
+        validateInitial?: boolean;
+    }): RoundSignal<T> & {
+        /** Signal containing the current validation error message. */
+        error: RoundSignal<string | null>;
+        /** Manually trigger validation check. Returns true if valid. */
+        check(): boolean
+    };
+    /**
+     * Creates a read/write view of a specific property path.
+     */
+    $pick<K extends keyof T>(path: K): RoundSignal<T[K]>;
+    $pick(path: string | string[]): RoundSignal<any>;
+    /**
+     * Internal: marks the signal as bindable for two-way bindings.
+     */
+    bind?: boolean;
+}
+/**
+ * Creates a reactive signal.
+ */
+export function signal<T>(initialValue?: T): RoundSignal<T>;
+/**
+ * Creates a bindable signal intended for two-way DOM bindings.
+ */
+export function bindable<T>(initialValue?: T): RoundSignal<T>;
+/**
+ * Run a function without tracking any signals it reads.
+ * Any signals accessed inside the function will not become dependencies of the current effect.
+ */
+export function untrack<T>(fn: () => T): T;
+/**
+ * Create a reactive side-effect that runs whenever its signal dependencies change.
+ */
+export function effect(fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+/**
+ * Create a reactive side-effect with explicit dependencies.
+ */
+export function effect(deps: any[], fn: () => void | (() => void), options?: {
+    /** If false, the effect won't run immediately on creation. Defaults to true. */
+    onLoad?: boolean
+}): () => void;
+/**
+ * Create a read-only computed signal derived from other signals.
+ */
+export function derive<T>(fn: () => T): () => T;
+/**
+ * Create a read/write view of a specific path within a signal object.
+ */
+export function pick<T = any>(root: RoundSignal<any>, path: string | string[]): RoundSignal<T>;
+/**
+ * Store API
+ */
+export interface RoundStore<T> {
+    /**
+     * Access a specific key from the store as a bindable signal.
+     */
+    use<K extends keyof T>(key: K): RoundSignal<T[K]>;
+    /**
+     * Update a specific key in the store.
+     */
+    set<K extends keyof T>(key: K, value: T[K]): T[K];
+    /**
+     * Batch update multiple keys in the store.
+     */
+    patch(obj: Partial<T>): void;
+    /**
+     * Get a snapshot of the current state.
+     */
+    snapshot(options?: {
+        /** If true, the returned values will be reactive signals. */
+        reactive?: boolean
+    }): T;
+    /**
+     * Enable persistence for the store.
+     */
+    persist(storageKey: string, options?: {
+        /** The storage implementation (defaults to localStorage). */
+        storage?: Storage;
+        /** Debounce time in milliseconds for writes. */
+        debounce?: number;
+        /** Array of keys to exclude from persistence. */
+        exclude?: string[];
+    }): RoundStore<T>;
+    /**
+     * Action methods defined during store creation.
+     */
+    actions: Record<string, Function>;
+}
+/**
+ * Create a shared global state store with actions and optional persistence.
+ */
+export function createStore<T, A extends Record<string, (state: T, ...args: any[]) => Partial<T> | void>>(
+    initialState: T,
+    actions?: A
+): RoundStore<T> & { [K in keyof A]: (...args: Parameters<A[K]> extends [any, ...infer P] ? P : never) => any };
+/**
+ * Router API
+ */
+export interface RouteProps {
+    /** The path to match. Must start with a forward slash. */
+    route?: string;
+    /** If true, only matches if the path is exactly the same. */
+    exact?: boolean;
+    /** Page title to set in the document header when active. */
+    title?: string;
+    /** Meta description to set in the document header when active. */
+    description?: string;
+    /** Advanced head configuration including links and meta tags. */
+    head?: any;
+    /** Fragment or elements to render when matched. */
+    children?: any;
+}
+/**
+ * Define a route that renders its children when the path matches.
+ */
+export function Route(props: RouteProps): any;
+/**
+ * An alias for Route, typically used for top-level pages.
+ */
+export function Page(props: RouteProps): any;
+export interface LinkProps {
+    /** The destination path. */
+    href: string;
+    /** Alias for href. */
+    to?: string;
+    /** Use SPA navigation (prevents full page reloads). Defaults to true. */
+    spa?: boolean;
+    /** Force a full page reload on navigation. */
+    reload?: boolean;
+    /** Custom click event handler. */
+    onClick?: (e: MouseEvent) => void;
+    /** Link content (text or elements). */
+    children?: any;
+    [key: string]: any;
+}
+/**
+ * A standard link component that performs SPA navigation.
+ */
+export function Link(props: LinkProps): any;
+/**
+ * Define a fallback component or content for when no routes match.
+ */
+export function NotFound(props: {
+    /** Optional component to render for the 404 state. */
+    component?: any;
+    /** Fallback content. ignored if 'component' is provided. */
+    children?: any
+}): any;
+/**
+ * Navigate to a different path programmatically.
+ */
+export function navigate(to: string, options?: {
+    /** If true, replaces the current history entry instead of pushing. */
+    replace?: boolean
+}): void;
+/**
+ * Hook to get a reactive function returning the current normalized pathname.
+ */
+export function usePathname(): () => string;
+/**
+ * Get the current normalized pathname.
+ */
+export function getPathname(): string;
+/**
+ * Hook to get a reactive function returning the current location object.
+ */
+export function useLocation(): () => { pathname: string; search: string; hash: string };
+/**
+ * Get the current location object (pathname, search, hash).
+ */
+export function getLocation(): { pathname: string; search: string; hash: string };
+/**
+ * Hook to get a reactive function returning whether the current path has no matches.
+ */
+export function useIsNotFound(): () => boolean;
+/**
+ * Get whether the current path is NOT matched by any defined route.
+ */
+export function getIsNotFound(): boolean;
+/**
+ * DOM & Context API
+ */
+/**
+ * Create a DOM element or instance a component.
+ */
+export function createElement(tag: any, props?: any, ...children: any[]): any;
+/**
+ * A grouping component that returns its children without a wrapper element.
+ */
+export function Fragment(props: { children?: any }): any;
+export interface Context<T> {
+    /** Internal identifier for the context. */
+    id: number;
+    /** Default value used when no Provider is found in the tree. */
+    defaultValue: T;
+    /** Component that provides a value to all its descendants. */
+    Provider: (props: { value: T; children?: any }) => any;
+}
+/**
+ * Create a new Context object for sharing state between components.
+ */
+export function createContext<T>(defaultValue?: T): Context<T>;
+/**
+ * Read the current value of a context from the component tree.
+ */
+export function readContext<T>(ctx: Context<T>): T;
+/**
+ * Returns a reactive function that reads the current context value.
+ */
+export function bindContext<T>(ctx: Context<T>): () => T;
+/**
+ * Async & Code Splitting
+ */
+/**
+ * Mark a component for lazy loading (code-splitting).
+ * Expects a function returning a dynamic import promise.
+ */
+export function lazy<T>(fn: () => Promise<{ default: T }>): T;
+export interface SuspenseProps {
+    /** Content to show while children (e.g. lazy components) are loading. */
+    fallback: any;
+    /** Content that might trigger a loading state. */
+    children?: any;
+}
+/**
+ * Component that boundaries async operations and renders a fallback while loading.
+ */
+export function Suspense(props: SuspenseProps): any;
+/**
+ * Head Management
+ */
+/**
+ * Define static head metadata (titles, meta tags, favicons, etc.).
+ */
+export function startHead(head: any): any;
+/**
+ * Markdown
+ */
+/**
+ * Component that renders Markdown content into HTML.
+ */
+export function Markdown(props: {
+    /** The markdown string or a function returning it. */
+    content: string | (() => string);
+    /** Remark/Rehype configuration options. */
+    options?: any
+}): any;

package/src/runtime/context.js CHANGED Viewed

@@ -11,6 +11,12 @@ function popContext() {
     contextStack.pop();
 }
+/**
+ * Read the current value of a context from the tree.
+ * @template T
+ * @param {Context<T>} ctx The context object.
+ * @returns {T} The current context value.
+ */
 export function readContext(ctx) {
     for (let i = contextStack.length - 1; i >= 0; i--) {
         const layer = contextStack[i];
@@ -21,6 +27,12 @@ export function readContext(ctx) {
     return ctx.defaultValue;
 }
+/**
+ * Create a new Context object for sharing state between components.
+ * @template T
+ * @param {T} [defaultValue] The value used when no provider is found.
+ * @returns {Context<T>} The context object with a `Provider` component.
+ */
 export function createContext(defaultValue) {
     const ctx = {
         id: nextContextId++,

package/src/runtime/dom.js CHANGED Viewed

@@ -29,6 +29,13 @@ function warnSignalDirectUsage(fn, kind) {
     }
 }
+/**
+ * Create a DOM element or instance a component.
+ * @param {string | Function} tag HTML tag name or Component function.
+ * @param {object} [props] Element attributes or component props.
+ * @param {...any} children Child nodes.
+ * @returns {Node} The resulting DOM node.
+ */
 export function createElement(tag, props = {}, ...children) {
     if (typeof tag === 'function') {
         const componentInstance = createComponentInstance();
@@ -388,6 +395,9 @@ function appendChild(parent, child) {
     }
 }
+/**
+ * A grouping component that returns its children without a wrapper element.
+ */
 export function Fragment(props) {
     return props.children;
 }

package/src/runtime/router.js CHANGED Viewed

@@ -127,6 +127,11 @@ function mountAutoNotFound() {
     root.appendChild(view);
 }
+/**
+ * Navigate to a different path programmatically.
+ * @param {string} to The destination URL or path.
+ * @param {object} [options] Navigation options (e.g., { replace: true }).
+ */
 export function navigate(to, options = {}) {
     if (!hasWindow) return;
     ensureListener();
@@ -264,6 +269,15 @@ export function setNotFound(Component) {
     defaultNotFoundComponent = Component;
 }
+/**
+ * Define a route that renders its children when the path matches.
+ * @param {object} props Route properties.
+ * @param {string} [props.route='/'] The path to match.
+ * @param {boolean} [props.exact] Whether to use exact matching.
+ * @param {string} [props.title] Page title to set when active.
+ * @param {string} [props.description] Meta description to set when active.
+ * @param {any} [props.children] Content to render.
+ */
 export function Route(props = {}) {
     ensureListener();
@@ -319,6 +333,10 @@ export function Route(props = {}) {
     });
 }
+/**
+ * An alias for Route, typically used for top-level pages.
+ * @param {object} props Page properties (same as Route).
+ */
 export function Page(props = {}) {
     ensureListener();
@@ -371,6 +389,9 @@ export function Page(props = {}) {
     });
 }
+/**
+ * Define a fallback component or content for when no routes match.
+ */
 export function NotFound(props = {}) {
     ensureListener();
@@ -402,6 +423,13 @@ export function NotFound(props = {}) {
     });
 }
+/**
+ * A standard link component that performs SPA navigation.
+ * @param {object} props Link properties.
+ * @param {string} [props.href] The destination path.
+ * @param {boolean} [props.spa=true] Use SPA navigation (prevents reload).
+ * @param {any} [props.children] Link content.
+ */
 export function Link(props = {}) {
     ensureListener();

package/src/runtime/signals.js CHANGED Viewed

@@ -12,6 +12,13 @@ function subscribe(running, subscriptions) {
     running.dependencies.add(subscriptions);
 }
+/**
+ * Run a function without tracking any signals it reads.
+ * Any signals accessed inside `fn` will not become dependencies of the current effect.
+ * @template T
+ * @param {() => T} fn The function to execute.
+ * @returns {T} The return value of `fn`.
+ */
 export function untrack(fn) {
     context.push(null);
     try {
@@ -21,6 +28,13 @@ export function untrack(fn) {
     }
 }
+/**
+ * Create a reactive side-effect that runs whenever its signal dependencies change.
+ * @param {(() => any) | any[]} arg1 Either the callback function or an array of explicit dependencies.
+ * @param {(() => any)} [arg2] The callback function if the first argument was explicit dependencies.
+ * @param {object} [arg3] Optional configuration (e.g., { onLoad: false }).
+ * @returns {() => void} A function to stop and cleanup the effect.
+ */
 export function effect(arg1, arg2, arg3) {
     let callback;
     let explicitDeps = null;
@@ -241,6 +255,12 @@ function attachHelpers(s) {
     return s;
 }
+/**
+ * Create a reactive signal.
+ * @template T
+ * @param {T} [initialValue] The starting value.
+ * @returns {RoundSignal<T>} A signal function that reads/writes the value.
+ */
 export function signal(initialValue) {
     let value = initialValue;
     const subscriptions = new Set();
@@ -285,6 +305,12 @@ export function signal(initialValue) {
     return attachHelpers(signal);
 }
+/**
+ * Create a bindable signal intended for two-way DOM bindings.
+ * @template T
+ * @param {T} [initialValue] The starting value.
+ * @returns {RoundSignal<T>} A signal function marked as bindable.
+ */
 export function bindable(initialValue) {
     const s = signal(initialValue);
     try {
@@ -345,6 +371,12 @@ function parsePath(path) {
     return [String(path)];
 }
+/**
+ * Create a read/write view of a specific path within a signal object.
+ * @param {RoundSignal<any>} root The source signal.
+ * @param {string | string[]} path The property path (e.g., 'user.profile.name' or ['user', 'profile', 'name']).
+ * @returns {RoundSignal<any>} A signal-like view of the path.
+ */
 export function pick(root, path) {
     if (!isSignalLike(root)) {
         throw new Error('[round] pick(root, path) expects root to be a signal (use bindable.object(...) or signal({...})).');
@@ -499,6 +531,12 @@ bindable.object = function (initialObject = {}) {
     return createBindableObjectProxy(root, []);
 };
+/**
+ * Create a read-only computed signal derived from other signals.
+ * @template T
+ * @param {() => T} fn A function that computes the value.
+ * @returns {(() => T)} A function that returns the derived value.
+ */
 export function derive(fn) {
     const derived = signal();

package/src/runtime/store.js CHANGED Viewed

@@ -5,6 +5,13 @@ function hasWindow() {
     return typeof window !== 'undefined' && typeof document !== 'undefined';
 }
+/**
+ * Create a shared global state store with actions and optional persistence.
+ * @template T
+ * @param {T} [initialState={}] Initial state object.
+ * @param {Record<string, (state: T, ...args: any[]) => any>} [actions] Action reducers.
+ * @returns {RoundStore<T>} The store object.
+ */
 export function createStore(initialState = {}, actions = null) {
     const state = (initialState && typeof initialState === 'object') ? initialState : {};
     const signals = Object.create(null);

package/vite.config.build.js CHANGED Viewed

@@ -33,4 +33,16 @@ export default defineConfig({
             }
         },
     },
+    plugins: [
+        {
+            name: 'copy-dts',
+            closeBundle() {
+                const src = path.resolve(__dirname, 'src/index.d.ts');
+                const dest = path.resolve(__dirname, 'dist/index.d.ts');
+                if (fs.existsSync(src)) {
+                    fs.copyFileSync(src, dest);
+                }
+            }
+        }
+    ]
 });