Unify plugin generated assets folder.

Author: koculu

frontend/purestack.studio/guides/content/image-optimization.mdx

@@ -62,7 +62,7 @@ For an eligible image, the plugin generates a `<picture>` with AVIF and WebP sou
 
 The plugin preserves `alt`, classes, IDs, styles, links around images, and author-supplied loading attributes. It fills missing `width` and `height` attributes from the image's oriented aspect ratio so the browser can reserve space. If you supply one dimension, the other is derived; if you supply both, both are kept.
 
-Generated images are written under `/_assets/images/`, with your site's `basePath` applied automatically. Filenames include a hash of the encoded bytes. Shared variants are reused across pages, and generated files are removed when no page references them. Original assets remain available at their usual URLs.
+Generated images are written under `/assets/images/`, with your site's `basePath` applied automatically. Filenames include a hash of the encoded bytes. Shared variants are reused across pages, and generated files are removed when no page references them. Original assets remain available at their usual URLs.
 
 Widths are sorted, deduplicated, and capped at the source image's dimensions. A 700-pixel-wide source with widths `[480, 960, 1440]` produces 480- and 700-pixel candidates for each format. The plugin never enlarges a source image.
 

packages/ts-common/src/site-assets.ts

@@ -22,7 +22,7 @@ export interface PageAssetInput {
 
 /** Each build/session owns its processors; core handles generated files and invalidation. */
 export interface SiteAssets {
-  /** A unique path segment under /_assets/. */
+  /** A unique path segment under /assets/. */
   namespace: string
   /** Ordered within a page; different pages may run concurrently. Input methods expire when this call completes. */
   processPage: (input: PageAssetInput) => void | Promise<void>

packages/ts-images/README.md

@@ -52,7 +52,7 @@ use `package#exportName` to select named plugins from installed packages.
 
 The plugin produces `<picture>` sources for the configured modern formats and
 an `<img>` with a JPEG/PNG fallback, `srcset`, `sizes`, and missing dimensions.
-Generated URLs live under `/_assets/images/`, with the site's base path applied
+Generated URLs live under `/assets/images/`, with the site's base path applied
 by PureStack. Filenames contain the hash of the **encoded output bytes**.
 Widths are deduplicated, sorted, and capped at the source's oriented dimensions.
 If `formats: []` is selected, only the responsive fallback is emitted, without a

packages/ts-ssg/README.md

@@ -453,7 +453,7 @@ The factory creates one processor per build/session. A page awaits each processo
 
 `input.document` is the rendered DOM, including component output. `await input.resolveSource(element, url)` resolves local assets using shared-content provenance and locale fallback, records source dependencies, and returns `{ relPath, absPath, publicPath }`. It returns `undefined` for external URLs. Sources must remain inside the content root. `input.dependOn(relPath)` records additional content-relative dependencies, including missing files that may appear later.
 
-`await input.emit(fileName, bytes)` writes a `Uint8Array` under `/_assets/<namespace>/` and returns an encoded root-relative URL. Use immutable, content-addressed filenames: emitting different bytes under the same name is an error. Core applies the site's base path during URL rewriting. Await all emission work before `processPage` returns, and inspect template fragments explicitly when relevant; `querySelectorAll` does not traverse their content.
+`await input.emit(fileName, bytes)` writes a `Uint8Array` under `/assets/<namespace>/` and returns an encoded root-relative URL. Use immutable, content-addressed filenames: emitting different bytes under the same name is an error. Core applies the site's base path during URL rewriting. Await all emission work before `processPage` returns, and inspect template fragments explicitly when relevant; `querySelectorAll` does not traverse their content.
 
 Core verifies existing output bytes on first use in each build/session. Repeated emissions reuse successful verification while file identity, size, and modification/change timestamps remain unchanged; changed files are checked again and repaired when necessary. Different-sized files are replaced without reading their obsolete contents. Symlink checks still run for every emission, and pruning or a new build clears the verification state.
 

packages/ts-ssg/src/build/assets.test.ts

@@ -554,10 +554,6 @@ describe('static assets', () => {
       )
       expect(runtimeFiles).toContain('chunks')
       expect(runtimeFiles.some((file) => file.startsWith('regor.'))).toBe(true)
-      await expect(
-        fs.stat(path.join(outDir, '_assets', 'runtime')),
-      ).rejects.toMatchObject({ code: 'ENOENT' })
-
       await expect(
         copyStaticAsset(
           root,

packages/ts-ssg/src/build/page-assets.test.ts

@@ -137,7 +137,7 @@ describe('page asset source tracking', () => {
 
   const bytes = Buffer.from('First')
   const output = (context: BuildContext) =>
-    path.join(context.config.outDir, '_assets', 'test', 'shared.txt')
+    path.join(context.config.outDir, 'assets', 'test', 'shared.txt')
   async function seed(value = bytes) {
     const file = output(context)
     await fs.mkdir(path.dirname(file), { recursive: true })

packages/ts-ssg/src/build/page-assets.ts

@@ -44,7 +44,7 @@ function reference(value: GeneratedAssetReference): GeneratedAssetReference {
   if (!validNamespace(value.namespace))
     throw new Error('Invalid generated asset namespace.')
   const relPath = relativeFile(value.path)
-  if (!relPath.startsWith(`_assets/${value.namespace}/`))
+  if (!relPath.startsWith(`assets/${value.namespace}/`))
     throw new Error('Generated output escapes its namespace.')
   return { namespace: value.namespace, path: relPath }
 }
@@ -231,7 +231,7 @@ export class PageAssetManager {
             emit: async (name, data) => {
               const file = reference({
                 namespace: processor.namespace,
-                path: `_assets/${processor.namespace}/${relativeFile(name)}`,
+                path: `assets/${processor.namespace}/${relativeFile(name)}`,
               })
               if (
                 !collected.outputs.some((output) => output.path === file.path)

packages/ts-ssg/src/plugins/assets.test.ts

@@ -229,15 +229,15 @@ describe('generic page assets', () => {
     await builder.renderByUrlPath('/a/')
     expect(
       await fs.readFile(
-        path.join(outDir, '_assets', 'files', 'shared.txt'),
+        path.join(outDir, 'assets', 'files', 'shared.txt'),
         'utf8',
       ),
     ).toBe('Shared')
     release?.()
     expect(await pending).toBe(true)
     expect(
       (await readManifest(outDir))?.pageAssets?.['c.md'].outputs[0].path,
-    ).toBe('_assets/files/shared.txt')
+    ).toBe('assets/files/shared.txt')
   })
 
   it('keeps generated files leased to concurrent renders and marks an in-flight dependent dirty', async () => {
@@ -312,7 +312,7 @@ describe('generic page assets', () => {
     input.options = { ...input.options, writeErrorPages: true }
     await buildSite(input)
     await expect(
-      fs.stat(path.join(outDir, '_assets', 'files', 'unused.txt')),
+      fs.stat(path.join(outDir, 'assets', 'files', 'unused.txt')),
     ).rejects.toMatchObject({ code: 'ENOENT' })
     expect((await readManifest(outDir))?.pageAssets?.['a.md']).toEqual({
       dependencies: ['source.txt'],
@@ -340,7 +340,7 @@ describe('generic page assets', () => {
     await buildSite(input)
     const state = (await readManifest(outDir))?.pageAssets?.['a.md']
     expect(state).toEqual({ dependencies: ['source.txt'], outputs: [] })
-    expect(await fs.readdir(path.join(outDir, '_assets', 'files'))).toEqual([])
+    expect(await fs.readdir(path.join(outDir, 'assets', 'files'))).toEqual([])
     expect(
       await fs.readFile(path.join(outDir, 'a', 'index.html'), 'utf8'),
     ).toContain('Written hook failed')
@@ -357,20 +357,20 @@ describe('generic page assets', () => {
     await buildSite(input)
     expect(
       await fs.readFile(path.join(outDir, 'a', 'index.html'), 'utf8'),
-    ).toContain('/_assets/files/a%20%23.txt')
-    await fs.mkdir(path.join(contentDir, '_assets', 'files'), {
+    ).toContain('/assets/files/a%20%23.txt')
+    await fs.mkdir(path.join(contentDir, 'assets', 'files'), {
       recursive: true,
     })
     await fs.writeFile(
-      path.join(contentDir, '_assets', 'files', 'a #.txt'),
+      path.join(contentDir, 'assets', 'files', 'a #.txt'),
       'Source',
     )
     await expect(buildSite(input)).rejects.toThrow(
       /conflicts with (?:a source output|a generated asset)/,
     )
     expect(
       await fs.readFile(
-        path.join(contentDir, '_assets', 'files', 'a #.txt'),
+        path.join(contentDir, 'assets', 'files', 'a #.txt'),
         'utf8',
       ),
     ).toBe('Source')
@@ -383,7 +383,7 @@ describe('generic page assets', () => {
       const { input, contentDir } = await fixture(async (input) => {
         if (!scriptUrl) throw new Error('Expected script URL')
         await input.emit(
-          scriptUrl.replace('/_assets/files/', ''),
+          scriptUrl.replace('/assets/files/', ''),
           Buffer.from('Generated'),
         )
       })
@@ -400,13 +400,13 @@ describe('generic page assets', () => {
       })
       await fs.writeFile(
         path.join(contentDir, 'a.md'),
-        '<PageScript src="./_assets/files/script.tS"/>',
+        '<PageScript src="./assets/files/script.tS"/>',
       )
-      await fs.mkdir(path.join(contentDir, '_assets', 'files'), {
+      await fs.mkdir(path.join(contentDir, 'assets', 'files'), {
         recursive: true,
       })
       await fs.writeFile(
-        path.join(contentDir, '_assets', 'files', 'script.tS'),
+        path.join(contentDir, 'assets', 'files', 'script.tS'),
         'export const value = 1',
       )
       await expect(buildSite(input)).rejects.toThrow(
@@ -422,23 +422,23 @@ describe('generic page assets', () => {
     })
     input.siteConfig = { ...input.siteConfig, scripts: { cacheBusting: false } }
     input.options?.plugins?.push(componentsPlugin())
-    await fs.mkdir(path.join(contentDir, '_assets', 'files'), {
+    await fs.mkdir(path.join(contentDir, 'assets', 'files'), {
       recursive: true,
     })
     await fs.writeFile(
-      path.join(contentDir, '_assets', 'files', 'script.ts'),
+      path.join(contentDir, 'assets', 'files', 'script.ts'),
       'export const value = 1',
     )
     await fs.writeFile(
       path.join(contentDir, 'b.md'),
-      '<PageScript src="./_assets/files/script.ts"/>',
+      '<PageScript src="./assets/files/script.ts"/>',
     )
     await expect(buildSite(input)).rejects.toThrow(
       'conflicts with a generated asset',
     )
     expect(
       await fs.readFile(
-        path.join(outDir, '_assets', 'files', 'script.js'),
+        path.join(outDir, 'assets', 'files', 'script.js'),
         'utf8',
       ),
     ).toBe('Generated')
@@ -475,7 +475,7 @@ describe('generic page assets', () => {
       'input is closed',
     )
     await expect(
-      fs.stat(path.join(outDir, '_assets', 'files', 'late.txt')),
+      fs.stat(path.join(outDir, 'assets', 'files', 'late.txt')),
     ).rejects.toMatchObject({ code: 'ENOENT' })
   })
 
@@ -487,7 +487,7 @@ describe('generic page assets', () => {
       'must await all source resolution and emission work',
     )
     await expect(
-      fs.stat(path.join(outDir, '_assets', 'files', 'detached.txt')),
+      fs.stat(path.join(outDir, 'assets', 'files', 'detached.txt')),
     ).rejects.toMatchObject({ code: 'ENOENT' })
   })
 

packages/ts-ssg/src/plugins/images.test.ts

@@ -82,7 +82,7 @@ describe('optional images plugin', () => {
     fs.readFile(path.join(outDir, file), 'utf8')
   async function generated(outDir: string) {
     return (
-      await fs.readdir(path.join(outDir, '_assets', 'images')).catch(() => [])
+      await fs.readdir(path.join(outDir, 'assets', 'images')).catch(() => [])
     ).sort()
   }
 
@@ -95,7 +95,7 @@ describe('optional images plugin', () => {
     const expectedFiles = await generated(outDir)
     const expectedBytes = await Promise.all(
       expectedFiles.map((file) =>
-        fs.readFile(path.join(outDir, '_assets', 'images', file)),
+        fs.readFile(path.join(outDir, 'assets', 'images', file)),
       ),
     )
     // A site-only package exercises fallback resolution without competing with
@@ -157,7 +157,7 @@ describe('optional images plugin', () => {
     expect(
       await Promise.all(
         expectedFiles.map((file) =>
-          fs.readFile(path.join(outDir, '_assets', 'images', file)),
+          fs.readFile(path.join(outDir, 'assets', 'images', file)),
         ),
       ),
     ).toEqual(expectedBytes)
@@ -202,7 +202,7 @@ describe('optional images plugin', () => {
       const image = document.querySelector('picture > img')
       expect(image?.getAttribute('alt')).toBe('A dashboard')
       expect(image?.getAttribute('src')).toMatch(
-        /^\/docs\/_assets\/images\/[a-f0-9]{64}\.64\.png$/,
+        /^\/docs\/assets\/images\/[a-f0-9]{64}\.64\.png$/,
       )
       expect(image?.getAttribute('width')).toBe('64')
       expect(image?.getAttribute('height')).toBe('32')
@@ -221,7 +221,7 @@ describe('optional images plugin', () => {
     })
     for (const file of await generated(outDir)) {
       const metadata = await sharp(
-        await fs.readFile(path.join(outDir, '_assets', 'images', file)),
+        await fs.readFile(path.join(outDir, 'assets', 'images', file)),
       ).metadata()
       expect(metadata.width).toBeLessThanOrEqual(64)
       expect(
@@ -251,7 +251,7 @@ describe('optional images plugin', () => {
         ).toBe('Photo')
         expect(
           document.querySelector('picture > img')?.getAttribute('src'),
-        ).toMatch(/^\/docs\/_assets\/images\//)
+        ).toMatch(/^\/docs\/assets\/images\//)
       },
     )
   })
@@ -325,7 +325,7 @@ describe('optional images plugin', () => {
     await runInDom(output, (document) => {
       expect(
         document.querySelector('img[alt="Header"]')?.getAttribute('src'),
-      ).toContain('/docs/_assets/images/')
+      ).toContain('/docs/assets/images/')
       expect(
         (
           document.querySelector('template') as HTMLTemplateElement
@@ -476,7 +476,7 @@ describe('optional images plugin', () => {
       expect(document.querySelectorAll('img[srcset]')).toHaveLength(2)
       expect(
         document.querySelector('img[alt="Hook"]')?.getAttribute('src'),
-      ).toContain('/docs/_assets/images/')
+      ).toContain('/docs/assets/images/')
     })
   })
 
@@ -508,7 +508,7 @@ describe('optional images plugin', () => {
     expect(
       (
         await sharp(
-          await fs.readFile(path.join(secondOutput, '_assets', 'images', file)),
+          await fs.readFile(path.join(secondOutput, 'assets', 'images', file)),
         ).metadata()
       ).width,
     ).toBe(24)
@@ -611,7 +611,7 @@ describe('optional images plugin', () => {
     expect(response.status).toBe(200)
     const output = await response.text()
     const urls =
-      output.match(/\/docs\/_assets\/images\/[a-f0-9]+\.\d+\.(?:avif|webp)/g) ??
+      output.match(/\/docs\/assets\/images\/[a-f0-9]+\.\d+\.(?:avif|webp)/g) ??
       []
     expect(urls.length).toBeGreaterThan(0)
     for (const extension of ['avif', 'webp']) {