@jk2908/solas 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.3.0 - 2026-04-07
+
+- Fixed `useSearchParams()` hydration so query-driven ui uses the initial request url on first render.
+- Switched internal runtime and generated imports to explicit `.js` specifiers, and corrected the router action import path.
+- Simplified generated config, manifest, and route map output to emit source literals directly.
+- Removed the generated-file formatting pass and deleted the internal `Format` helper.
+- Documented that the Solas cli currently requires Bun 1.2+ on `PATH`.
+
+## 0.2.3 - 2026-04-02
+
+- Previous release.

package/README.md

@@ -4,6 +4,8 @@ Solas is a minimal React meta-framework powered by Vite, created for experimenti
 
 It has not been rigorously tested yet (there are currently no automated tests) ... and broken behaviour should be expected.
 
+Solas currently requires Bun 1.2+ on your `PATH`. You can still manage dependencies with `npm`, `pnpm`, or `yarn`, but the Solas CLI and Vite plugin runtime use Bun APIs directly.
+
 ## Install
 
 ```sh
@@ -315,9 +317,9 @@ export default defineConfig(({ mode }) => ({
 		solas({
 			url: mode === 'production' ? 'https://example.com' : 'http://localhost:8787',
 			sitemap: {
-				async routes(discovered) {
-					const posts = await fetchPostSlugs()
-					return [...discovered, ...posts.map(s => `/blog/${s}`)]
+				async routes(existing) {
+					const posts = await getPosts()
+					return [...existing, ...posts.map(p => `/blog/${p.slug}`)]
 				},
 			},
 		}),

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { Solas } from './solas';
-import { Compress } from './utils/compress';
-import { Logger } from './utils/logger';
-import { Prerender } from './internal/prerender';
+import { Solas } from './solas.js';
+import { Compress } from './utils/compress.js';
+import { Logger } from './utils/logger.js';
+import { Prerender } from './internal/prerender.js';
 const logger = new Logger();
 const DEFAULT_PREVIEW_PORT = 4173;
 /**
@@ -52,10 +52,21 @@ async function build() {
         const concurrency = Prerender.Build.getConcurrency();
         // track the extra prerender files we write for preview
         const artifactManifestRoutes = {};
+        // keep in-flight artifact writes bounded so result handling does not block on one route at a time
+        const pendingWrites = new Set();
         logger.info('[prerender]', `prerendering ${manifest.prerenderRoutes.length} routes (timeout: ${timeout}ms, concurrency: ${concurrency})...`);
         // load the built server entry and render each prerendered route through it
         const rscEntry = path.join(rscDir, 'index.js');
         const { default: app } = await import(/* @vite-ignore */ rscEntry);
+        async function enqueueWrite(task) {
+            const write = task().finally(() => {
+                pendingWrites.delete(write);
+            });
+            pendingWrites.add(write);
+            if (pendingWrites.size >= concurrency) {
+                await Promise.race(pendingWrites);
+            }
+        }
         // run prerender through the built app so build output uses the same path as preview
         for await (const result of Prerender.Build.run(app, manifest.prerenderRoutes, {
             timeout,
@@ -63,98 +74,81 @@ async function build() {
             origin: manifest.url,
         })) {
             const route = result.route;
-            try {
-                // store prerender metadata for this route under the framework folder
-                const artifactDir = Prerender.Artifact.getPath(outDir, route);
-                if ('error' in result)
-                    throw result.error;
-                if ('status' in result) {
-                    logger.warn('[prerender]', `skipped ${route}: ${result.status}`);
-                    continue;
-                }
-                const artifact = result.artifact;
-                if (artifact.mode === 'ppr') {
-                    // for ppr save the shell now and keep the postponed state for later
+            if ('error' in result) {
+                logger.error(`[prerender]: Failed ${route}: ${result.error}. This often means unresolved async work (for example external fetches or dynamic rendering in full mode)`);
+                continue;
+            }
+            if ('status' in result) {
+                logger.warn(`[prerender]: Skipped ${route}: ${result.status}`);
+                continue;
+            }
+            const artifact = result.artifact;
+            const artifactDir = Prerender.Artifact.getPath(outDir, route);
+            await enqueueWrite(async () => {
+                try {
+                    if (artifact.mode === 'ppr') {
+                        // for ppr save the shell now and keep the postponed state for later
+                        await fs.mkdir(artifactDir, { recursive: true });
+                        const writes = [
+                            Bun.write(path.join(artifactDir, 'prelude.html'), artifact.html),
+                            Bun.write(path.join(artifactDir, 'metadata.json'), JSON.stringify({
+                                schema: artifact.schema,
+                                route: artifact.route,
+                                createdAt: artifact.createdAt,
+                                mode: artifact.mode,
+                            })),
+                        ];
+                        if (artifact.postponed !== undefined) {
+                            writes.push(Bun.write(path.join(artifactDir, 'postponed.json'), JSON.stringify(artifact.postponed)));
+                        }
+                        await Promise.all(writes);
+                        artifactManifestRoutes[route] = {
+                            mode: artifact.mode,
+                            createdAt: artifact.createdAt,
+                            files: artifact.postponed !== undefined
+                                ? ['metadata', 'prelude', 'postponed']
+                                : ['metadata', 'prelude'],
+                        };
+                        logger.info('[prerender:artifacts]', JSON.stringify({
+                            route,
+                            prelude: artifact.html,
+                            postponed: artifact.postponed ?? null,
+                            metadata: {
+                                schema: artifact.schema,
+                                route: artifact.route,
+                                createdAt: artifact.createdAt,
+                                mode: artifact.mode,
+                            },
+                        }));
+                        logger.info('[prerender]', `${route} (ppr)`);
+                        return;
+                    }
+                    // full prerender still keeps metadata so preview knows to serve saved html
                     await fs.mkdir(artifactDir, { recursive: true });
-                    const writes = [
-                        Bun.write(path.join(artifactDir, 'prelude.html'), artifact.html),
+                    const fullPrerenderFilename = Prerender.Artifact.getFullHtmlFileName(artifact.html);
+                    await Promise.all([
                         Bun.write(path.join(artifactDir, 'metadata.json'), JSON.stringify({
                             schema: artifact.schema,
                             route: artifact.route,
                             createdAt: artifact.createdAt,
                             mode: artifact.mode,
                         })),
-                    ];
-                    if (artifact.postponed !== undefined) {
-                        writes.push(Bun.write(path.join(artifactDir, 'postponed.json'), JSON.stringify(artifact.postponed)));
-                    }
-                    await Promise.all(writes);
+                        Bun.write(Prerender.Artifact.getFilePath(outDir, route, fullPrerenderFilename), artifact.html),
+                    ]);
                     artifactManifestRoutes[route] = {
                         mode: artifact.mode,
                         createdAt: artifact.createdAt,
-                        files: artifact.postponed !== undefined
-                            ? ['metadata', 'prelude', 'postponed']
-                            : ['metadata', 'prelude'],
+                        files: ['metadata', 'html'],
+                        fullPrerenderFilename,
                     };
-                    logger.info('[prerender:artifacts]', JSON.stringify({
-                        route,
-                        prelude: artifact.html,
-                        postponed: artifact.postponed ?? null,
-                        metadata: {
-                            schema: artifact.schema,
-                            route: artifact.route,
-                            createdAt: artifact.createdAt,
-                            mode: artifact.mode,
-                        },
-                    }));
-                    logger.info('[prerender]', `${route} (ppr)`);
-                    continue;
+                    logger.info(`[prerender]: ${route} (full)`);
                 }
-                // @todo: hash files
-                // full prerender still keeps metadata so preview knows to serve saved html
-                await fs.mkdir(artifactDir, { recursive: true });
-                await Bun.write(path.join(artifactDir, 'metadata.json'), JSON.stringify({
-                    schema: artifact.schema,
-                    route: artifact.route,
-                    createdAt: artifact.createdAt,
-                    mode: artifact.mode,
-                }));
-                const routePath = route.replace(/^\//, '').replace(/\/$/, '');
-                const outPath = route === '/'
-                    ? path.join(outDir, 'index.html')
-                    : manifest.trailingSlash === 'always'
-                        ? path.join(outDir, routePath, 'index.html')
-                        : path.join(outDir, `${routePath}.html`);
-                // remove the old file shape for this route so switching trailingSlash mode does not leave
-                // both variants behind. we have to do this before writing the new file so that if the
-                // route shape changes, we still remove the old one instead of leaving in the output
-                const alternateOutPath = route === '/'
-                    ? null
-                    : manifest.trailingSlash === 'always'
-                        ? path.join(outDir, `${routePath}.html`)
-                        : path.join(outDir, routePath, 'index.html');
-                if (alternateOutPath) {
-                    // remove the old file shape so switching trailingSlash mode
-                    // does not leave both variants behind
-                    await Promise.all([
-                        fs.rm(alternateOutPath, { force: true }),
-                        fs.rm(`${alternateOutPath}.br`, { force: true }),
-                    ]);
-                    await fs.rmdir(path.dirname(alternateOutPath)).catch(() => { });
+                catch (err) {
+                    logger.error(`[prerender]: Failed ${route}: ${err}. This often means unresolved async work (for example external fetches or dynamic rendering in full mode).`);
                 }
-                await fs.mkdir(path.dirname(outPath), { recursive: true });
-                await Bun.write(outPath, artifact.html);
-                artifactManifestRoutes[route] = {
-                    mode: artifact.mode,
-                    createdAt: artifact.createdAt,
-                    files: ['metadata', 'html'],
-                };
-                logger.info('[prerender]', `${route} (full)`);
-            }
-            catch (err) {
-                logger.error('[prerender]', `failed ${route}: ${err}. This often means unresolved async work (for example external fetches or dynamic rendering in full mode).`);
-            }
+            });
         }
+        await Promise.all(pendingWrites);
         // write one manifest for the saved prerender files after all routes finish
         await fs.mkdir(artifactRoot, { recursive: true });
         await Bun.write(Prerender.Artifact.getManifestPath(outDir), JSON.stringify({
@@ -224,7 +218,7 @@ async function preview() {
         await fs.access(rscEntry);
     }
     catch (err) {
-        logger.error(`[preview] missing ${path.relative(cwd, rscEntry)} - run \`${Solas.Config.SLUG} build\` first`, err);
+        logger.error(`[preview] missing ${path.relative(cwd, rscEntry)} - run \`${Solas.Config.SLUG} build\` from this project directory first`, err);
         process.exit(1);
     }
     const { default: app } = await import(/* @vite-ignore */ rscEntry);

package/dist/error-boundary.d.ts

@@ -1 +1 @@
-export { ErrorBoundary } from './internal/ui/error-boundary';
+export { ErrorBoundary } from './internal/ui/error-boundary.js';

package/dist/error-boundary.js

@@ -1 +1 @@
-export { ErrorBoundary } from './internal/ui/error-boundary';
+export { ErrorBoundary } from './internal/ui/error-boundary.js';

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { PluginOption } from 'vite';
-import type { PluginConfig } from './types';
+import type { PluginConfig } from './types.js';
 declare function solas(c: PluginConfig): PluginOption[];
 export default solas;
-export { Solas } from './solas';
 export type * from './solas.d.ts';
-export type * from './types';
+export { Solas } from './solas.js';
+export type * from './types.js';

package/dist/index.js

@@ -2,16 +2,15 @@ import fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import rsc from '@vitejs/plugin-rsc';
-import { Solas } from './solas';
-import { ExportReader } from './utils/export-reader';
-import { Format } from './utils/format';
-import { Logger } from './utils/logger';
-import { Time } from './utils/time';
-import { Build } from './internal/build';
-import { writeConfig } from './internal/codegen/config';
-import { writeBrowserEntry, writeRSCEntry, writeSSREntry, } from './internal/codegen/environments';
-import { writeManifest } from './internal/codegen/manifest';
-import { writeMaps } from './internal/codegen/maps';
+import { ExportReader } from './utils/export-reader.js';
+import { Logger } from './utils/logger.js';
+import { Time } from './utils/time.js';
+import { Build } from './internal/build.js';
+import { writeConfig } from './internal/codegen/config.js';
+import { writeBrowserEntry, writeRSCEntry, writeSSREntry, } from './internal/codegen/environments.js';
+import { writeManifest } from './internal/codegen/manifest.js';
+import { writeMaps } from './internal/codegen/maps.js';
+import { Solas } from './solas.js';
 const DEFAULT_CONFIG = {
     precompress: true,
     prerender: false,
@@ -104,9 +103,6 @@ function solas(c) {
         // early return if nothing has changed
         if (!changed.length)
             return;
-        await Promise.all(changed.map(filePath => Format.run(filePath).catch(err => {
-            logger.error(`[build] Failed to format file: ${filePath}`, err);
-        })));
         return changed;
     }
     let rebuildRunning = false;
@@ -248,4 +244,4 @@ function solas(c) {
     ];
 }
 export default solas;
-export { Solas } from './solas';
+export { Solas } from './solas.js';

package/dist/internal/build.d.ts

@@ -1,4 +1,4 @@
-import type { BuildContext, Endpoint, PluginConfig, Segment } from '../types';
+import type { BuildContext, Endpoint, PluginConfig, Segment } from '../types.js';
 /**
  * Types, constants, and the Finder class for route discovery and manifest generation.
  * The Finder walks the app directory, builds inheritance chains, and transforms

package/dist/internal/build.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { Solas } from '../solas';
-import { Logger } from '../utils/logger';
-import { normalisePathname } from './router/utils';
-import { Prerender } from './prerender';
+import { Solas } from '../solas.js';
+import { Logger } from '../utils/logger.js';
+import { normalisePathname } from './router/utils.js';
+import { Prerender } from './prerender.js';
 export { Build };
 /**
  * Types, constants, and the Finder class for route discovery and manifest generation.

package/dist/internal/codegen/config.d.ts

@@ -1,4 +1,4 @@
-import type { PluginConfig } from '../../types';
+import type { PluginConfig } from '../../types.js';
 /**
  * Generates the code to create an exported config object
  */

package/dist/internal/codegen/config.js

@@ -1,19 +1,19 @@
-import { Solas } from '../../solas';
-import { AUTOGEN_MSG } from './utils';
+import { Solas } from '../../solas.js';
+import { AUTOGEN_MSG, toSourceLiteral } from './utils.js';
 /**
  * Generates the code to create an exported config object
  */
 export function writeConfig(config) {
     return `
-    ${AUTOGEN_MSG}
+		${AUTOGEN_MSG}
 
-    import type { PluginConfig } from '${Solas.Config.PKG_NAME}'
-    import { Logger } from '${Solas.Config.PKG_NAME}/utils/logger'
+		import type { PluginConfig } from '${Solas.Config.PKG_NAME}'
+		import { Logger } from '${Solas.Config.PKG_NAME}/utils/logger'
 
-    const config = ${JSON.stringify(config, null, 2)} as const satisfies PluginConfig
+		const config = ${toSourceLiteral(config)} as const satisfies PluginConfig
 
-    if (config.logger?.level) Logger.defaultLevel = config.logger.level
-    
-    export { config }
-  `.trim();
+		if (config.logger?.level) Logger.defaultLevel = config.logger.level
+
+		export { config }
+	`.trim();
 }

package/dist/internal/codegen/environments.js

@@ -1,42 +1,46 @@
-import { Solas } from '../../solas';
-import { AUTOGEN_MSG } from './utils';
+import { Solas } from '../../solas.js';
+import { AUTOGEN_MSG } from './utils.js';
 /**
  * Generates the RSC entry code
  */
 export function writeRSCEntry() {
     return `
-    ${AUTOGEN_MSG}
+		${AUTOGEN_MSG}
 
-    import { createHandler } from '${Solas.Config.PKG_NAME}/env/rsc'
+		import { createHandler } from '${Solas.Config.PKG_NAME}/env/rsc'
+		import { Prerender } from '${Solas.Config.PKG_NAME}/prerender'
+		import { Solas } from '${Solas.Config.PKG_NAME}'
 
-    import { manifest } from './manifest'
-    import { importMap } from './maps'
-    import { config } from './config'
+		import { manifest } from './manifest.js'
+		import { importMap } from './maps.js'
+		import { config } from './config.js'
 
-    export default createHandler(config, manifest, importMap)
+		const artifactManifest = await Prerender.Artifact.loadManifest(Solas.Config.OUT_DIR)
 
-    import.meta.hot?.accept()
-  `.trim();
+		export default createHandler(config, manifest, importMap, artifactManifest)
+
+		import.meta.hot?.accept()
+	`.trim();
 }
 /**
  * Generates the SSR entry code
  */
 export function writeSSREntry() {
     return `
-    ${AUTOGEN_MSG}
-    
-    export { prerender, resume, ssr } from '${Solas.Config.PKG_NAME}/env/ssr'
-  `.trim();
+		${AUTOGEN_MSG}
+
+		export { prerender, resume, ssr } from '${Solas.Config.PKG_NAME}/env/ssr'
+	`.trim();
 }
 /**
  * Generates the browser entry code
  */
 export function writeBrowserEntry() {
     return `
-    ${AUTOGEN_MSG}
+		${AUTOGEN_MSG}
 
-    import { browser } from '${Solas.Config.PKG_NAME}/env/browser'
+		import { browser } from '${Solas.Config.PKG_NAME}/env/browser'
 
-    browser()
-  `.trim();
+		browser()
+	`.trim();
 }

package/dist/internal/codegen/manifest.d.ts

@@ -1,4 +1,4 @@
-import type { Manifest } from '../../types';
+import type { Manifest } from '../../types.js';
 /**
  * Generates the code to create an exported manifest object
  */

package/dist/internal/codegen/manifest.js

@@ -1,15 +1,14 @@
-import { Solas } from '../../solas';
-import { AUTOGEN_MSG } from './utils';
+import { Solas } from '../../solas.js';
+import { AUTOGEN_MSG, toSourceLiteral } from './utils.js';
 /**
  * Generates the code to create an exported manifest object
  */
 export function writeManifest(manifest) {
     return `
-    ${AUTOGEN_MSG}
+		${AUTOGEN_MSG}
 
-    import type { Manifest } from '${Solas.Config.PKG_NAME}'
+		import type { Manifest } from '${Solas.Config.PKG_NAME}'
 
-    export const manifest = 
-      ${JSON.stringify(manifest, null, 2)} as const satisfies Manifest
-  `.trim();
+		export const manifest = ${toSourceLiteral(manifest)} as const satisfies Manifest
+	`.trim();
 }

package/dist/internal/codegen/maps.d.ts

@@ -1,4 +1,4 @@
-import type { Build } from '../build';
+import type { Build } from '../build.js';
 /**
  * Generates the import map for all route components, endpoints, layouts, shells, and middlewares
  */

package/dist/internal/codegen/maps.js

@@ -1,5 +1,5 @@
-import { Solas } from '../../solas';
-import { AUTOGEN_MSG } from './utils';
+import { Solas } from '../../solas.js';
+import { AUTOGEN_MSG, toIdentifier, toIdentifierList, toRelativeModuleSpecifier, toStringLiteral, } from './utils.js';
 /**
  * Generates the import map for all route components, endpoints, layouts, shells, and middlewares
  */
@@ -7,69 +7,80 @@ export function writeMaps(imports, modules) {
     const statics = [
         ...imports.endpoints.static.entries().map(([k, v]) => {
             const [, method] = k.split('_');
-            return `import { ${method.toUpperCase()} as ${k}} from ${JSON.stringify(v)}`.trim();
+            return `import { ${toIdentifier(method.toUpperCase(), `endpoint export for ${k}`)} as ${toIdentifier(k, `endpoint alias for ${v}`)} } from ${toRelativeModuleSpecifier(v, `endpoint import for ${k}`)}`;
         }),
         ...imports.components.static
             .entries()
-            .map(([k, v]) => `import * as ${k} from ${JSON.stringify(v)}`.trim()),
+            .map(([k, v]) => `import * as ${toIdentifier(k, `component alias for ${v}`)} from ${toRelativeModuleSpecifier(v, `component import for ${k}`)}`),
         ...imports.middlewares.static
             .entries()
-            .map(([k, v]) => `import { middleware as ${k} } from ${JSON.stringify(v)}`.trim()),
+            .map(([k, v]) => `import { middleware as ${toIdentifier(k, `middleware alias for ${v}`)} } from ${toRelativeModuleSpecifier(v, `middleware import for ${k}`)}`),
     ];
     const dynamics = [
         ...imports.components.dynamic
             .entries()
-            .map(([k, v]) => `export const ${k} = () => import(${JSON.stringify(v)})`.trim()),
+            .map(([k, v]) => `export const ${toIdentifier(k, `dynamic component alias for ${v}`)} = () => import(${toRelativeModuleSpecifier(v, `dynamic import for ${k}`)})`),
     ];
-    const map = Object.entries(modules).map(([id, m]) => {
+    const map = Object.entries(modules).map(([moduleId, m]) => {
         const parts = [];
-        if (m.shellId)
-            parts.push(`shell: ${m.shellId}`);
+        if (m.shellId) {
+            parts.push(`shell: ${toIdentifier(m.shellId, `shell id for ${moduleId}`)}`);
+        }
         if (m.layoutIds?.length) {
-            const layouts = m.layoutIds.map(id => (id === null ? 'null' : id)).join(', ');
+            const layouts = toIdentifierList(m.layoutIds, `layouts for ${moduleId}`);
             parts.push(`layouts: [${layouts}]`);
         }
-        if (m.pageId)
-            parts.push(`page: ${m.pageId}`);
-        if (m.endpointId)
-            parts.push(`endpoint: ${m.endpointId}`);
+        if (m.pageId) {
+            parts.push(`page: ${toIdentifier(m.pageId, `page id for ${moduleId}`)}`);
+        }
+        if (m.endpointId) {
+            parts.push(`endpoint: ${toIdentifier(m.endpointId, `endpoint id for ${moduleId}`)}`);
+        }
         if (m['401Ids']?.length) {
-            const unauthorized = m['401Ids'].map(id => (id === null ? 'null' : id)).join(', ');
+            const unauthorized = toIdentifierList(m['401Ids'], `401s for ${moduleId}`);
             parts.push(`'401s': [${unauthorized}]`);
         }
         if (m['403Ids']?.length) {
-            const forbidden = m['403Ids'].map(id => (id === null ? 'null' : id)).join(', ');
+            const forbidden = toIdentifierList(m['403Ids'], `403s for ${moduleId}`);
             parts.push(`'403s': [${forbidden}]`);
         }
         if (m['404Ids']?.length) {
-            const notFounds = m['404Ids'].map(id => (id === null ? 'null' : id)).join(', ');
+            const notFounds = toIdentifierList(m['404Ids'], `404s for ${moduleId}`);
             parts.push(`'404s': [${notFounds}]`);
         }
         if (m['500Ids']?.length) {
-            const serverErrors = m['500Ids'].map(id => (id === null ? 'null' : id)).join(', ');
+            const serverErrors = toIdentifierList(m['500Ids'], `500s for ${moduleId}`);
             parts.push(`'500s': [${serverErrors}]`);
         }
         if (m.loadingIds?.length) {
-            const loaders = m.loadingIds.map(id => (id === null ? 'null' : id)).join(', ');
+            const loaders = toIdentifierList(m.loadingIds, `loaders for ${moduleId}`);
             parts.push(`loaders: [${loaders}]`);
         }
         if (m.middlewareIds?.length) {
-            const middleware = m.middlewareIds.map(id => (id === null ? 'null' : id)).join(', ');
+            const middleware = toIdentifierList(m.middlewareIds, `middlewares for ${moduleId}`);
             parts.push(`middlewares: [${middleware}]`);
         }
-        return `${JSON.stringify(id)}: { ${parts.join(', ')} }`;
+        if (parts.length === 0)
+            return `\t${toStringLiteral(moduleId)}: {}`;
+        return `\t${toStringLiteral(moduleId)}: {\n\t\t${parts.join(',\n\t\t')}\n\t}`;
     });
     return `
-	  ${AUTOGEN_MSG}
+		${AUTOGEN_MSG}
 
 		import type { ImportMap } from '${Solas.Config.PKG_NAME}'
 
-	  ${statics.join('\n')}
-		
-	  ${dynamics.join('\n')}
+		${statics.length
+        ? `${statics.join('\n')}
+
+		`
+        : ''}${dynamics.length
+        ? `${dynamics.join('\n')}
+
+		`
+        : ''}
 
 		export const importMap = {
-			${map.join(',\n')}
+		${map.join(',\n')}
 		} as const satisfies ImportMap
-	`;
+	`.trim();
 }

package/dist/internal/codegen/utils.d.ts

@@ -1 +1,21 @@
 export declare const AUTOGEN_MSG = "// auto-generated by Solas";
+/**
+ * Validate an identifier before writing it into generated source unquoted
+ */
+export declare function toIdentifier(value: string, label: string): string;
+/**
+ * Validate and quote a relative specifier before embedding it in generated imports
+ */
+export declare function toRelativeModuleSpecifier(value: string, label: string): string;
+/**
+ * Validate a nullable identifier list whilst preserving explicit null holes
+ */
+export declare function toIdentifierList(values: readonly (string | null)[], label: string): string;
+/**
+ * Escape text into a safe string literal for generated source
+ */
+export declare function toStringLiteral(value: string, quoteStyle?: "'" | '"'): string;
+/**
+ * Emit readable ts source for generated config and manifest data
+ */
+export declare function toSourceLiteral(value: unknown, level?: number): string;