@temir.ra/create-ts-lib 0.2.7-pre.1 → 0.3.0

package/CHANGELOG.md

@@ -1,8 +1,26 @@
 # Version 0
 
-## 0.2.7-pre.1
+## 0.3.0
+
+1. Removed AI Assistant Context files to be generated by the user with the provided prompts in the README.
+
+## 0.2.8 (unreleased)
+
+1. CLI now copies root `README.md` into the generated project as `README-template.md`.
+2. Added `README-template.md` to `template/gitignore`.
+3. Added `# AI Assistant Context` section to root `README.md` and `template/README.md` with prompts for generating AI coding assistant context files.
+4. Revised Change Management step 6 in root `README.md` and `template/README.md`.
+5. `.gitignore`'ing `bun.lock`.
+
+## 0.2.8-pre.2
+
+1. Removed `sideEffects` property from `package.json` as it is not a standard field.
+2. Added references to npmjs and typescriptlang documentation for `package.json` and `tsconfig.json` in the README.
+
+## 0.2.7
 
 1. Changed `filter` property in `cdnRewritePlugin` in `scripts/build-lib-bundle.ts` to take import identifiers into account that do not have file extensions.
+2. Changed `buildinfo.txt` generation in `scripts/buildinfo.ts` to read the version from `package.json` instead of relying on the `npm_package_version` environment variable. Enables correct version capture in monorepo setups.
 
 ## 0.2.6
 

package/README.md

@@ -5,7 +5,8 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [Documentation](#documentation)
+2. [AI Assistant Context](#ai-assistant-context)
+3. [Documentation](#documentation)
     1. [`tsconfig.json` and `tsconfig.build.json`](#tsconfigjson-and-tsconfigbuildjson)
     2. [`package.json`](#packagejson)
     3. [Script `scripts/buildinfo.ts`](#script-scriptsbuildinfots)
@@ -21,8 +22,7 @@ A template for TypeScript libraries distributed via npm-compatible registries. P
             3. [README statement for library consumers](#readme-statement-for-library-consumers)
             4. [When the library is bundled by the consumer](#when-the-library-is-bundled-by-the-consumer)
     8. [`src/dev.ts`](#srcdevts)
-    9. [`CLAUDE.md` / `AGENTS.md`](#claudemd--agentsmd)
-3. [DevOps](#devops)
+4. [DevOps](#devops)
     1. [Change Management](#change-management)
     2. [Publish](#publish)
         1. [npmjs.org](#npmjsorg)
@@ -54,12 +54,20 @@ cd <NEW_PACKAGE>
 bun install
 ```
 
+# AI Assistant Context
+
+To generate an AI coding assistant context file for this project:
+
+> Generate an AI coding assistant context file. Analyze the project structure and source files, using this README as the primary reference for architecture and conventions. Give particular attention to: the dual tsconfig setup and the import constraints it imposes, the `#src/*.js` alias and where it may and may not be used, the custom `entrypoint` export condition, and the asset resolution contract.
+
 # Documentation
 
 The following sections explain the configurations and conventions baked into the generated package. Useful when adapting the generated package to fit a specific library's needs.
 
 ## `tsconfig.json` and `tsconfig.build.json`
 
+See the typescriptlang documentation on [tsconfig.json](https://www.typescriptlang.org/tsconfig) for detailed explanations of all options.
+
 ```json
 {
 
@@ -184,6 +192,8 @@ The following sections explain the configurations and conventions baked into the
 
 ## `package.json`
 
+See npmjs documentation on [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json) for detailed explanations of all fields.
+
 ```json
 {
   "name": "",
@@ -203,10 +213,6 @@ The following sections explain the configurations and conventions baked into the
   // treats all .js files as ES modules; use .cjs extension for CommonJS files
   "type": "module",
 
-  // no module has side effects; enables full tree-shaking by bundlers
-  // set to an array of file paths if some modules do have side effects, e.g. ["./src/polyfill.ts"]
-  "sideEffects": false,
-
   // package entry points by consumer type
   // "entrypoint" - custom condition; used by the bundle script to locate the source entry point
   // "types"      - TypeScript consumers; resolves to the declaration files; must precede "import" so TypeScript matches it before the JS condition
@@ -418,13 +424,6 @@ From the bundle's perspective `assets/@scope/lib-name/` is at the same directory
 
 Development scratchpad - not published, excluded from `tsconfig.build.json`. Run with `bun run dev` in watch mode. Use it to manually test and explore library code during development.
 
-## `CLAUDE.md` / `AGENTS.md`
-
-AI assistant context files. Provide project layout, commands, and architecture notes. `AGENTS.md` references `CLAUDE.md`. The template ships two pairs:
-
-- Root pair - describes the template package itself (scaffolding tool, CLI, how `template/` maps to generated projects)
-- `template/` pair - describes the generated library project; update to reflect the specific library being developed
-
 # DevOps
 
 ```bash
@@ -451,7 +450,7 @@ bun run dist/cli.bundle.js -- example
 3. Bump the version in [`package.json`](package.json).
 4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
 5. Pull request the branch.
-6. After merge, run `bun run build`.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
 7. Publish.
 
 ## Publish

package/buildinfo.txt

@@ -1 +1 @@
-0.2.7-pre.1+1fa806e
+0.3.0+e1e7c7f

package/dist/cli.bundle.js

@@ -1,4 +1,4 @@
 #!/usr/bin/env node
-import{cpSync as n,readFileSync as c,renameSync as p,writeFileSync as l}from"fs";import{resolve as t,basename as m}from"path";import{fileURLToPath as g}from"url";var f=new URL("../",import.meta.url),r=t(g(f)),d=t(r,"template/"),h=t(r,"CHANGELOG.md"),u=t(r,"buildinfo.txt");try{let a=process.argv[2];if(!a)throw Error("Destination path is required. Usage: `bun/npm create <template> <destination>`");let e=t(process.cwd(),a),o=m(e);n(d,e,{recursive:!0}),n(h,t(e,"CHANGELOG-template.md")),n(u,t(e,"buildinfo-template.txt"));let s=t(e,"package.json"),i=JSON.parse(c(s,"utf-8"));i.name=o,l(s,JSON.stringify(i,null,2)),p(t(e,"gitignore"),t(e,".gitignore")),console.log(`Template has been successfully instantiated at '${e}' with package name '${o}'.`)}catch(a){let e=a instanceof Error?a:Error(String(a));console.error("Error:",e.message),process.exit(1)}
+import{cpSync as n,readFileSync as c,renameSync as m,writeFileSync as p}from"fs";import{resolve as e,basename as l}from"path";import{fileURLToPath as g}from"url";var d=new URL("../",import.meta.url),r=e(g(d)),f=e(r,"template/"),h=e(r,"CHANGELOG.md"),u=e(r,"buildinfo.txt"),E=e(r,"README.md");try{let a=process.argv[2];if(!a)throw Error("Destination path is required. Usage: `bun/npm create <template> <destination>`");let t=e(process.cwd(),a),o=l(t);n(f,t,{recursive:!0}),n(h,e(t,"CHANGELOG-template.md")),n(u,e(t,"buildinfo-template.txt")),n(E,e(t,"README-template.md"));let s=e(t,"package.json"),i=JSON.parse(c(s,"utf-8"));i.name=o,p(s,JSON.stringify(i,null,2)),m(e(t,"gitignore"),e(t,".gitignore")),console.log(`Template has been successfully instantiated at '${t}' with package name '${o}'.`)}catch(a){let t=a instanceof Error?a:Error(String(a));console.error("Error:",t.message),process.exit(1)}
 
-//# debugId=27529CB64FC389F464756E2164756E21
+//# debugId=969CCBE42ED5C5D964756E2164756E21

package/dist/cli.bundle.js.map

@@ -2,9 +2,9 @@
   "version": 3,
   "sources": ["..\\src\\cli.ts"],
   "sourcesContent": [
-    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nconst packageUrl = new URL('../', import.meta.url);\r\nconst packagePath = resolve(fileURLToPath(packageUrl));\r\n\r\nconst templatePath = resolve(packagePath, 'template/');\r\n\r\nconst changelogPath = resolve(packagePath, 'CHANGELOG.md');\r\nconst buildinfoPath = resolve(packagePath, 'buildinfo.txt');\r\n\r\n\r\ntry {\r\n\r\n    const dest = process.argv[2];\r\n    if (!dest) throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');\r\n\r\n    const destinationPath = resolve(process.cwd(), dest);\r\n    const packageName = basename(destinationPath);\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n\r\n    const packageManifestPath = resolve(destinationPath, 'package.json');\r\n    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));\r\n    packageManifest.name = packageName;\r\n    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, null, 2));\r\n\r\n    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));\r\n\r\n    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);\r\n\r\n}\r\ncatch (error) {\r\n    const err = error instanceof Error ? error : new Error(String(error));\r\n    console.error('Error:', err.message);\r\n    process.exit(1);\r\n}\r\n"
+    "#!/usr/bin/env node\r\n\r\nimport { cpSync, readFileSync, renameSync, writeFileSync } from 'fs';\r\nimport { resolve, basename } from 'path';\r\nimport { fileURLToPath } from 'url';\r\n\r\n\r\nconst packageUrl = new URL('../', import.meta.url);\r\nconst packagePath = resolve(fileURLToPath(packageUrl));\r\n\r\nconst templatePath = resolve(packagePath, 'template/');\r\n\r\nconst changelogPath = resolve(packagePath, 'CHANGELOG.md');\r\nconst buildinfoPath = resolve(packagePath, 'buildinfo.txt');\r\nconst readmePath = resolve(packagePath, 'README.md');\r\n\r\n\r\ntry {\r\n\r\n    const dest = process.argv[2];\r\n    if (!dest) throw new Error('Destination path is required. Usage: `bun/npm create <template> <destination>`');\r\n\r\n    const destinationPath = resolve(process.cwd(), dest);\r\n    const packageName = basename(destinationPath);\r\n\r\n    cpSync(templatePath, destinationPath, { recursive: true });\r\n    cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));\r\n    cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));\r\n    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));\r\n\r\n    const packageManifestPath = resolve(destinationPath, 'package.json');\r\n    const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));\r\n    packageManifest.name = packageName;\r\n    writeFileSync(packageManifestPath, JSON.stringify(packageManifest, null, 2));\r\n\r\n    renameSync(resolve(destinationPath, 'gitignore'), resolve(destinationPath, '.gitignore'));\r\n\r\n    console.log(`Template has been successfully instantiated at '${destinationPath}' with package name '${packageName}'.`);\r\n\r\n}\r\ncatch (error) {\r\n    const err = error instanceof Error ? error : new Error(String(error));\r\n    console.error('Error:', err.message);\r\n    process.exit(1);\r\n}\r\n"
   ],
-  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,cAAS,aAClB,wBAAS,YAGT,IAAM,EAAa,IAAI,IAAI,MAAO,YAAY,GAAG,EAC3C,EAAc,EAAQ,EAAc,CAAU,CAAC,EAE/C,EAAe,EAAQ,EAAa,WAAW,EAE/C,EAAgB,EAAQ,EAAa,cAAc,EACnD,EAAgB,EAAQ,EAAa,eAAe,EAG1D,GAAI,CAEA,IAAM,EAAO,QAAQ,KAAK,GAC1B,GAAI,CAAC,EAAM,MAAU,MAAM,gFAAgF,EAE3G,IAAM,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAI,EAC7C,EAAc,EAAS,CAAe,EAE5C,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAe,EAAQ,EAAiB,uBAAuB,CAAC,EACvE,EAAO,EAAe,EAAQ,EAAiB,wBAAwB,CAAC,EAExE,IAAM,EAAsB,EAAQ,EAAiB,cAAc,EAC7D,EAAkB,KAAK,MAAM,EAAa,EAAqB,OAAO,CAAC,EAC7E,EAAgB,KAAO,EACvB,EAAc,EAAqB,KAAK,UAAU,EAAiB,KAAM,CAAC,CAAC,EAE3E,EAAW,EAAQ,EAAiB,WAAW,EAAG,EAAQ,EAAiB,YAAY,CAAC,EAExF,QAAQ,IAAI,mDAAmD,yBAAuC,KAAe,EAGzH,MAAO,EAAO,CACV,IAAM,EAAM,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EACpE,QAAQ,MAAM,SAAU,EAAI,OAAO,EACnC,QAAQ,KAAK,CAAC",
-  "debugId": "27529CB64FC389F464756E2164756E21",
+  "mappings": ";AAEA,iBAAS,kBAAQ,gBAAc,mBAAY,WAC3C,kBAAS,cAAS,aAClB,wBAAS,YAGT,IAAM,EAAa,IAAI,IAAI,MAAO,YAAY,GAAG,EAC3C,EAAc,EAAQ,EAAc,CAAU,CAAC,EAE/C,EAAe,EAAQ,EAAa,WAAW,EAE/C,EAAgB,EAAQ,EAAa,cAAc,EACnD,EAAgB,EAAQ,EAAa,eAAe,EACpD,EAAa,EAAQ,EAAa,WAAW,EAGnD,GAAI,CAEA,IAAM,EAAO,QAAQ,KAAK,GAC1B,GAAI,CAAC,EAAM,MAAU,MAAM,gFAAgF,EAE3G,IAAM,EAAkB,EAAQ,QAAQ,IAAI,EAAG,CAAI,EAC7C,EAAc,EAAS,CAAe,EAE5C,EAAO,EAAc,EAAiB,CAAE,UAAW,EAAK,CAAC,EACzD,EAAO,EAAe,EAAQ,EAAiB,uBAAuB,CAAC,EACvE,EAAO,EAAe,EAAQ,EAAiB,wBAAwB,CAAC,EACxE,EAAO,EAAY,EAAQ,EAAiB,oBAAoB,CAAC,EAEjE,IAAM,EAAsB,EAAQ,EAAiB,cAAc,EAC7D,EAAkB,KAAK,MAAM,EAAa,EAAqB,OAAO,CAAC,EAC7E,EAAgB,KAAO,EACvB,EAAc,EAAqB,KAAK,UAAU,EAAiB,KAAM,CAAC,CAAC,EAE3E,EAAW,EAAQ,EAAiB,WAAW,EAAG,EAAQ,EAAiB,YAAY,CAAC,EAExF,QAAQ,IAAI,mDAAmD,yBAAuC,KAAe,EAGzH,MAAO,EAAO,CACV,IAAM,EAAM,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EACpE,QAAQ,MAAM,SAAU,EAAI,OAAO,EACnC,QAAQ,KAAK,CAAC",
+  "debugId": "969CCBE42ED5C5D964756E2164756E21",
   "names": []
 }

package/dist/cli.js

@@ -7,6 +7,7 @@ const packagePath = resolve(fileURLToPath(packageUrl));
 const templatePath = resolve(packagePath, 'template/');
 const changelogPath = resolve(packagePath, 'CHANGELOG.md');
 const buildinfoPath = resolve(packagePath, 'buildinfo.txt');
+const readmePath = resolve(packagePath, 'README.md');
 try {
     const dest = process.argv[2];
     if (!dest)
@@ -16,6 +17,7 @@ try {
     cpSync(templatePath, destinationPath, { recursive: true });
     cpSync(changelogPath, resolve(destinationPath, 'CHANGELOG-template.md'));
     cpSync(buildinfoPath, resolve(destinationPath, 'buildinfo-template.txt'));
+    cpSync(readmePath, resolve(destinationPath, 'README-template.md'));
     const packageManifestPath = resolve(destinationPath, 'package.json');
     const packageManifest = JSON.parse(readFileSync(packageManifestPath, 'utf-8'));
     packageManifest.name = packageName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@temir.ra/create-ts-lib",
-  "version": "0.2.7-pre.1",
+  "version": "0.3.0",
   "description": "Typescript library template",
   "author": "temir.ra",
   "license": "MIT",
@@ -15,7 +15,6 @@
     "url": "https://git.chimps.quest/trs/create-ts-lib.git"
   },
   "type": "module",
-  "sideEffects": false,
   "imports": {
     "#src/*.js": "./src/*.ts"
   },

package/template/README.md

@@ -5,8 +5,9 @@
 ## Table of Contents
 
 1. [Quick Start](#quick-start)
-2. [Documentation](#documentation)
-3. [DevOps](#devops)
+2. [AI Assistant Context](#ai-assistant-context)
+3. [Documentation](#documentation)
+4. [DevOps](#devops)
     1. [Change Management](#change-management)
     2. [Publish](#publish)
         1. [npmjs.org](#npmjsorg)
@@ -36,6 +37,12 @@ bun run dev
 
 **Publish** - see [Publish](#publish).
 
+# AI Assistant Context
+
+To generate an AI coding assistant context file for this project:
+
+> Generate an AI coding assistant context file. `README-template.md` is available now and documents the architectural conventions of this package — use it as your primary source. The generated context file must be self-contained: `README-template.md` will be deleted after context generation, so do not reference it in the output. Give particular attention to: the dual tsconfig setup and the import constraints it imposes, the `#src/*.js` alias and where it may and may not be used, the custom `entrypoint` export condition, and the asset resolution contract.
+
 # Documentation
 
 *<DOCUMENTATION>*
@@ -46,11 +53,11 @@ bun run dev
 
 Assets are placed under `assets/@scope/lib-name/` (scoped to the package name to prevent collisions). They are resolved at runtime via `import.meta.url` and loaded with `fetch()` (browser) or `readFile` (Node). `assets/` must be listed in `files` in `package.json`.
 
-`import.meta.url` is reliable when the library is loaded as a discrete module (from CDN or `node_modules/`). When the consumer bundles the library, they must copy the assets — see below.
+`import.meta.url` is reliable when the library is loaded as a discrete module (from CDN or `node_modules/`). When the consumer bundles the library, they must copy the assets - see below.
 
 ### For consumers bundling this library
 
-Copy `node_modules/@scope/lib-name/assets/` into your build output alongside the bundle, preserving the relative path. No code configuration is required — only the file copy.
+Copy `node_modules/@scope/lib-name/assets/` into your build output alongside the bundle, preserving the relative path. No code configuration is required - only the file copy.
 
 # DevOps
 
@@ -61,7 +68,7 @@ Copy `node_modules/@scope/lib-name/assets/` into your build output alongside the
 3. Bump the version in [`package.json`](package.json).
 4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
 5. Pull request the branch.
-6. After merge, run `bun run build`.
+6. After merge, run `bun run build` - ensures artifacts are current before publish.
 7. Publish.
 
 ## Publish

package/template/gitignore

@@ -4,3 +4,4 @@ buildinfo.txt
 *.tsbuildinfo
 buildinfo-template.txt
 CHANGELOG-template.md
+README-template.md

package/template/package.json

@@ -12,7 +12,6 @@
     "url": ""
   },
   "type": "module",
-  "sideEffects": false,
   "exports": {
     ".": {
       "entrypoint": "./src/index.ts",

package/template/scripts/buildinfo.ts

@@ -1,11 +1,11 @@
 import { execSync } from 'child_process';
-import { writeFileSync } from 'fs';
+import { readFileSync, writeFileSync } from 'fs';
 
 
 const BUILD_INFO_FILE = 'buildinfo.txt';
 const GIT_COMMAND = 'git rev-parse --short HEAD';
 
-const version = process.env.npm_package_version ?? '0.0.0';
+const { version } = JSON.parse(readFileSync('package.json', 'utf-8'));
 
 let gitHash = '';
 try {

package/template/AGENTS.md

@@ -1 +0,0 @@
-See [CLAUDE.md](CLAUDE.md).

package/template/CLAUDE.md

@@ -1,216 +0,0 @@
-# <package-name>
-
-A Bun TypeScript library.
-
-## Project Layout
-
-```
-<package-name>/
-├── src/
-│   ├── index.ts        # Library entry point (public API)
-│   └── dev.ts          # Development scratchpad — run with `bun run dev`
-├── scripts/
-│   ├── buildinfo.ts            # Writes version + git hash to buildinfo.txt
-│   ├── build-lib-bundle.ts     # Bundles the library for ESM + CDN distribution
-│   └── cdn-rewrite-map.json    # CDN import rewrite rules (empty by default)
-├── tests/              # Unit tests (Bun test runner)
-├── dist/               # Build output (gitignored)
-├── buildinfo.txt       # Written during build; included in published package
-├── CHANGELOG.md        # Version history
-├── CLAUDE.md           # This file — AI context for the library project
-└── AGENTS.md           # References CLAUDE.md
-```
-
-## Commands
-
-```bash
-bun install       # Install dependencies
-bun run build     # Compile + bundle the library
-bun run tests     # Run unit tests
-bun run typecheck # Type-check without emitting
-bun run dev       # Run src/dev.ts in watch mode
-bun run clean              # Remove dist/ and tsconfig.build.tsbuildinfo
-bun run clean:dist         # Remove dist/ only
-bun run clean:tsbuildinfo  # Remove tsconfig.build.tsbuildinfo only
-```
-
-## Writing Code
-
-### Where things go
-
-| Path | Purpose |
-|------|---------|
-| `src/index.ts` | Public API — the only entry point consumers see; export everything public from here |
-| `src/*.ts` | Library source modules — add new modules here, re-export from `index.ts` |
-| `src/dev.ts` | Development scratchpad — excluded from build, never published; use for manual testing |
-| `tests/*.test.ts` | Unit tests — Bun test runner |
-
-### Imports within `src/`
-
-`tsconfig.build.json` uses `moduleResolution: nodenext`, so imports between library source files must use explicit `.js` extensions:
-
-```ts
-import { helper } from "./helper.js"  // ✓
-import { helper } from "./helper"     // ✗ — fails under nodenext
-```
-
-The `#src/*.js` package alias is available in `dev.ts`, `tests/`, and `scripts/`, but **not** in library source files — tsc emits the specifier verbatim and it would break in published unbundled output.
-
-### Explicit return types (`isolatedDeclarations`)
-
-All exported declarations require explicit type annotations so tsc can emit `.d.ts` files without cross-file inference:
-
-```ts
-export function greet(name: string): string { ... }  // ✓
-export function greet(name: string) { ... }          // ✗ — implicit return type
-```
-
-### Type-only imports (`verbatimModuleSyntax`)
-
-Use `import type` for imports that are only used as types:
-
-```ts
-import type { Foo } from "./foo.js"       // ✓ — type-only import
-import { type Foo, bar } from "./foo.js"  // ✓ — mixed
-import { Foo } from "./foo.js"            // ✗ — if Foo is only used as a type
-```
-
-### Asset Resolution (if the library has runtime assets)
-
-The key question: **does your library retain its own URL at runtime?** Everything else follows from it.
-
-- **Externalized** (loaded from CDN or `node_modules/`): `import.meta.url` is reliable as-is — no consumer action needed.
-- **Bundled** (absorbed into the consumer's output): `import.meta.url` points to the consumer's bundle, not the library's file. The path relationship can be preserved by convention — if the consumer copies the library's assets into their build output at the same relative path, resolution continues to work correctly.
-
-#### Contract
-
-**The library must:**
-1. Place assets in a scoped directory — `assets/@scope/lib-name/` (mirrors the package name, prevents collisions when multiple libraries share a consumer bundle).
-2. Access assets via `import.meta.url` — see code below.
-3. Document the bundled case in the library's README — see [README statement](#readme-statement-for-consumers) below.
-
-**The consumer must,**
-- **when loading the library externalized:** do nothing.
-- **when bundling the library:** copy `node_modules/@scope/lib-name/assets/` into their build output alongside the bundle, and ensure the assets are served.
-
-#### Scoped assets directory
-
-```
-assets/
-└── @scope/
-    └── lib-name/
-        └── <ASSETS>
-```
-
-Add `assets/` to `files` in `package.json` so it is included in the published package:
-
-```json
-"files": ["dist", "CHANGELOG.md", "buildinfo.txt", "assets"]
-```
-
-#### Accessing assets
-
-Resolve asset URLs inline from `import.meta.url` — no shared helper file:
-
-```typescript
-const packageUrl = new URL('../', import.meta.url);
-const assetsUrl  = new URL('assets/@scope/lib-name/', packageUrl);
-
-// for --target browser
-const data = await fetch(new URL('data.json', assetsUrl)).then(r => r.json());
-
-// for --target node
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'url';
-const raw = await readFile(fileURLToPath(new URL('data.json', assetsUrl)), 'utf-8');
-```
-
-#### When the library is bundled by the consumer
-
-The consumer must copy assets into their build output at the same relative path:
-
-```
-consumer output/
-├── bundle.js               ← import.meta.url points here
-└── assets/
-    └── @scope/
-        └── lib-name/
-            └── <ASSETS>    ← copied; relative path preserved
-```
-
-No code configuration needed — only the file copy.
-
-#### README statement for consumers
-
-Copy the following into the library's README (replace `<SCOPE>` and `<LIB_NAME>`):
-
-```markdown
-## Asset resolution
-
-This library resolves assets at runtime using `import.meta.url`. If you bundle this library into your application, copy `node_modules/<SCOPE>/<LIB_NAME>/assets/<SCOPE>/<LIB_NAME>/` into your build output directory alongside your bundle.
-```
-
-### Tests
-
-Tests live in `tests/` and use Bun's built-in runner:
-
-```ts
-import { describe, test, expect } from "bun:test"
-
-describe("greet", () => {
-  test("returns greeting", () => {
-    expect(greet("world")).toBe("hello, world")
-  })
-})
-```
-
-Run with `bun run tests`.
-
-## TypeScript Configuration
-
-Two tsconfig files serve different purposes:
-
-| File | Purpose |
-|------|---------|
-| `tsconfig.json` | Development — no emit, includes `src/`, `tests/`, `scripts/` |
-| `tsconfig.build.json` | Build — emits JS + `.d.ts`, `src/` only (excludes `dev.ts`, tests, scripts) |
-
-`bun run build:lib` uses `tsconfig.build.json`. During development the runtime handles TypeScript directly so no compilation step is needed.
-
-Both configs enable an extended strict type-safety profile beyond `strict`: `verbatimModuleSyntax`, `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`, `noImplicitOverride`, `isolatedDeclarations`.
-
-## Build Outputs
-
-`bun run build` runs two steps in sequence:
-
-1. **`build:lib`** — `tsc --project tsconfig.build.json` → `dist/*.js` + `dist/*.d.ts`
-2. **`build:lib-bundle`** — `scripts/build-lib-bundle.ts` → `dist/index.bundle.js` (ESM, minified) + `dist/index.iife.js` (IIFE, minified)
-
-The `exports` field in `package.json` maps consumers to the right file:
-
-| Condition | File |
-|-----------|------|
-| `types` | `dist/index.d.ts` |
-| `browser` | `dist/index.bundle.js` |
-| `import` | `dist/index.js` |
-
-## Package Configuration
-
-Key `package.json` fields:
-
-- `"sideEffects": false` — enables full tree-shaking by bundlers
-- `"imports": { "#src/*.js": "./src/*.ts" }` — package-internal alias for `src/`; use as `import { foo } from "#src/module.js"`. **Only for `dev.ts`, `tests/`, and `scripts/`** — not for library source files compiled by `tsconfig.build.json`, as tsc emits the specifier verbatim and it would break in published unbundled output.
-
-## Change Management
-
-1. Branch off main.
-2. Make the changes and commit.
-3. Bump the version in [`package.json`](package.json).
-4. Add an entry for the new version in [`CHANGELOG.md`](CHANGELOG.md).
-5. Pull request the branch.
-6. After merge, run `bun run build`. ← must happen after merge so `buildinfo.txt` captures the correct git hash, and before publish so the artifacts are up to date.
-7. Publish.
-
-## Publishing
-
-See [README.md](README.md) for registry setup and publish commands.