@vp-tw/dirwell 0.1.0-alpha.1 → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @vp-tw/dirwell
 
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- Keep the bundled attribution link usable outside a repository checkout and align the API documentation with declared-target symlink navigation.
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- Document published-package onboarding, selective build-tool support, troubleshooting, and current alpha release procedures. Lead the README and docs with a working folder-to-website path before advanced configuration.
+
 ## 0.1.0-alpha.1
 
 ### Patch Changes

package/README.md

@@ -1,183 +1,89 @@
 # Dirwell
 
-Dirwell turns a directory into a static file explorer. Build files for a static
-host, or serve a changing folder locally. Choose SSG for portable output and
-MPA when many directory pages should share assets.
+Turn a folder of downloads, reports, or build artifacts into a searchable website.
+Dirwell generates the file list, directory navigation, and links to the original
+files. Publish the output on a static host; visitors do not need a Dirwell server.
 
-## Quick start
+[Try the live explorer](https://vp-tw.github.io/dirwell/examples/file-icons/) ·
+[Get started](https://vp-tw.github.io/dirwell/getting-started/) ·
+[Documentation](https://vp-tw.github.io/dirwell/overview/)
 
-```bash
-pnpm install
-pnpm dirwell serve ./fixture
-pnpm dirwell build ./fixture -o ./generated
-```
+## Browse your first folder
+
+You need **Node.js 26 or later**, which includes npm. From a terminal, replace
+`./downloads` with a folder that already exists:
 
-These commands run from a repository checkout. The first starts a watch server;
-the second writes a static tree. The installed CLI uses the same `dirwell`
-commands. Existing `index.html` and `index.htm` files are preserved; Dirwell
-uses `_dirwell.html` for those directories when that name is available.
-
-| Need                                 | Start with                                  |
-| ------------------------------------ | ------------------------------------------- |
-| Move the output tree between paths   | SSG and relative URLs, the defaults         |
-| Publish beneath a fixed path         | `base` plus `urls: "base"`                  |
-| Share assets across many pages       | `mode: "mpa"`                               |
-| Show only selected source files      | `include` and `exclude`                     |
-| Change icons or a few UI parts       | `createDefaultTheme({ icons, components })` |
-| Render basic HTML without JavaScript | `createPlainTheme()`                        |
-
-The [configuration guide](./docs/src/content/docs/configuration.md) lists
-accepted values, defaults, effects, and use cases for every field.
-
-```text
-dirwell [directory]          # alias for serve
-dirwell serve [directory]    # watch and live reload
-dirwell build [directory]    # generate static output
-dirwell daemon start [dir]   # detached server
-dirwell daemon status
-dirwell daemon stop
+```bash
+npx @vp-tw/dirwell@alpha serve ./downloads
 ```
 
-## Configuration
+Accept npm's installation prompt on first use. Open the `Local:` URL printed by
+Dirwell. Add or change a file to see the list update. Press Ctrl+C to stop.
+No repository clone or config file is required.
 
-Create `dirwell.config.ts` when a field has no CLI flag or you want a reusable
-setup:
+Dirwell is currently **alpha**. Use `@alpha` explicitly; the `latest` npm tag
+remains on the bootstrap alpha and does not select the newest alpha.
 
-```ts
-import { defineConfig } from "@vp-tw/dirwell";
+## Publish the folder
 
-export default defineConfig({
-  mode: "mpa",
-  base: "/downloads/",
-  urls: "base",
-  include: ["**/*.md", "assets/**"],
-  exclude: ["drafts/**"],
-});
+```bash
+npx @vp-tw/dirwell@alpha build ./downloads -o ./site-downloads
 ```
 
-Run `pnpm dirwell build ./public -o ./dist` to use it. The CLI's positional
-directory defaults to `.` and overrides config `root`, so pass the source
-path in the command.
-
-`outputName` accepts a fixed filename or a function receiving `DirectoryData`.
-Returning `null` skips the current directory. The default uses `index.html`,
-then `_dirwell.html` when an index already exists, then skips if both exist.
-
-`include` and `exclude` accept root-relative glob patterns. They select mirrored
-files, generated directory pages, and search results; exclusions win. With no
-patterns, every source entry is included.
+Upload the complete `site-downloads/` directory to a static host. The default
+output uses relative links so it can move between URL paths as one tree. The
+command replaces that output directory; keep unrelated files elsewhere.
+Existing source `index.html` and `index.htm` files are preserved, with the
+explorer written to `_dirwell.html` when that name is free.
 
-URL generation supports portable depth-aware `relative` links, Vite-style
-`base` prefixes for deployments such as GitHub Pages, and native
-`html-base` documents using `<base href>`.
+The default Ledger theme includes search, sorting, file icons, and keyboard
+navigation. Files open in a new tab; directory navigation stays in the explorer.
+Default output includes the listing in HTML and remains browsable without
+JavaScript. Advanced MPA output can use JavaScript for large directory lists.
 
-## Output modes
+## Use it in a project
 
-- `ssg` emits a page and runtime asset in every generated directory. This is
-  the default and works on simple static hosts.
-- `mpa` keeps every directory directly addressable while sharing runtime
-  assets from the output-root `__dirwell/` directory. The default theme moves
-  directories over 500 entries into a per-directory data asset and renders only
-  nearby rows, so these pages require JavaScript.
+Install the package when you need a reusable config, a theme, or a build adapter:
 
-`__dirwell/` is reserved in both modes for generated assets such as broken-link
-raw views.
-
-## Vite integration
+```bash
+npm install --save-dev @vp-tw/dirwell@alpha
+```
 
-The `@vp-tw/dirwell/vite` adapter builds one or more explorers alongside a Vite
-application and serves them through Vite's development server:
+Create `dirwell.config.ts` beside your project's `package.json`:
 
 ```ts
-import { defineConfig } from "vite";
-import Dirwell from "@vp-tw/dirwell/vite";
+import { defineConfig } from "@vp-tw/dirwell";
 
 export default defineConfig({
-  plugins: [
-    Dirwell([
-      { root: "./docs", outDir: "dist/docs" },
-      { root: "./downloads", outDir: "dist/downloads", mode: "mpa" },
-    ]),
-  ],
+  exclude: ["drafts/**"],
 });
 ```
 
-By default, Dirwell writes to a dedicated `dirwell/` subdirectory of Vite's
-`build.outDir` and derives its public `base` from Vite's base path. Set
-`outDir: "dist/downloads"` for another path relative to the Vite project root,
-or set an absolute `outDir` for an independent publish directory. An output
-outside Vite's build directory needs an explicit public `base`. The adapter
-never replaces Vite's output root or an existing directory it does not own.
-See [configuration](./docs/src/content/docs/configuration.md#vite-adapter) for
-the full path and development-server behavior.
-
-## Other build tools
-
-Adapters are available for Rollup, Rolldown, webpack, Rspack, Rsbuild, esbuild,
-Farm, and Bun. Import `@vp-tw/dirwell/<host>` or use the factories from
-`@vp-tw/dirwell/unplugin`. Each generates a dedicated explorer path alongside the host
-output. See [build tool adapters](./docs/src/content/docs/build-tools.md) for
-options, watch behavior, and verification boundaries.
-
-## Browser behavior
-
-SSG pages and smaller MPA pages work without JavaScript. The runtime adds local and global
-fuzzy search, type filters, configurable sorting, IME-safe keyboard controls,
-Backspace parent navigation, theme persistence, and watch-mode live reload. The
-global search index is fetched only after the user opens Search all files and types a query.
-The index is split into bounded files; the first 100 best matches render progressively.
-Search matches file names, relative paths, and symlink targets. Three independent
-type controls filter physical folders, physical files, and symlinks. All are on by
-default; any combination is available in the current folder and global search.
-
-Name sorting supports raw Unicode code-point order, locale-aware comparison,
-and natural numeric comparison. Modified time and file size are also available;
-direction and directory grouping are independent controls.
-
-The default theme shows modified times in the viewer's local time zone when
-JavaScript is available, without repeating the offset in every row. Activate a
-date with touch, pointer, or keyboard to see its exact local time and UTC instant.
-Generated HTML displays labeled UTC times before the
-runtime loads and when JavaScript is disabled. The plain theme always displays UTC.
-
-## Symlinks
-
-Symlinks always remain visible and show their declared target. Broken links can
-open their raw target text; targets outside the configured root remain
-unavailable. Broken links, outside-root targets, and cycles receive explicit states.
-Following directory links is opt-in. Ancestor cycles remain navigable but are
-never expanded recursively.
-
-## Themes
-
-Replace the complete `ExplorerTheme` or layer typed component overrides over
-the default theme. See [THEMING.md](./THEMING.md) and the Starlight site in
-`docs/`.
-
-`createPlainTheme()` provides a separate browser-native listing with no
-icons, JavaScript, appearance controls, or search index. It emits complete HTML
-in both modes; choose the default theme for search and large-directory
-virtualization. See [examples/plain](./examples/plain).
-Its footer shows the repository, author, and license. Pass `project` to
-`createPlainTheme()` to override the metadata and link to a published repository.
-
-The default theme uses selected self-hosted `vscode-icons` artwork for common
-file types. The icons are CC BY-SA 4.0 and may include separately protected
-brand marks; Dirwell's code remains MIT-licensed. See
-[Ledger theme attribution](./src/theme-default/README.md),
-[third-party notices](./THIRD_PARTY_NOTICES.md), and the
-[file-icons example](./examples/file-icons).
-
-## Development
+Run `npx dirwell build ./downloads -o ./site-downloads`. Pass the source folder
+explicitly: the CLI defaults to the current directory even if config sets `root`.
+Pin your tested version when you need reproducible alpha builds.
 
-```bash
-pnpm install
-pnpm test
-pnpm exec playwright install chromium --only-shell
-pnpm test:browser
-pnpm run check
-pnpm run build
-pnpm run docs:build
-```
+## Choose your next step
+
+| Need                                                 | Read                                                                                                            |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| Publish under a fixed path, such as GitHub Pages     | [Deployment](https://vp-tw.github.io/dirwell/deployment/)                                                       |
+| Select files, change output names, or configure URLs | [Configuration](https://vp-tw.github.io/dirwell/configuration/)                                                 |
+| Change the interface or use a no-script listing      | [Themes](https://vp-tw.github.io/dirwell/themes/)                                                               |
+| Generate alongside an existing application           | [Build tool adapters](https://vp-tw.github.io/dirwell/build-tools/)                                             |
+| Check supported integrations and limitations         | [Support policy](https://vp-tw.github.io/dirwell/support/)                                                      |
+| Call Dirwell from Node.js or write a theme package   | [API reference](https://vp-tw.github.io/dirwell/api-reference/) · [Theme contract](./THEME_PACKAGE_CONTRACT.md) |
+| Resolve setup, output, or link problems              | [Troubleshooting](https://vp-tw.github.io/dirwell/troubleshooting/)                                             |
+
+Build-tool support is selective. Vite, Rollup, and webpack are the primary
+integrations; the other existing adapters are experimental. Unplugin supplies
+shared plugin interfaces, not a promise that every tool or website framework
+has identical behavior. See the support policy before choosing an adapter.
+
+## Contribute
+
+For repository setup, tests, examples, architecture, and release instructions,
+see [Contributing](https://github.com/vp-tw/dirwell/blob/main/CONTRIBUTING.md).
 
-Dirwell is MIT licensed.
+Dirwell's code is MIT licensed. Ledger's bundled file icons have separate
+attribution and license terms in [third-party notices](./THIRD_PARTY_NOTICES.md).

package/THEME_PACKAGE_CONTRACT.md

@@ -5,9 +5,9 @@ An independent theme package exports a factory returning `ExplorerTheme` from
 renderer replacement is the smallest contract: the package owns its HTML,
 styles, assets, options, language controls, and browser behavior.
 
-The [external package example](examples/theme-package) exercises this boundary
+The [external package example](https://github.com/vp-tw/dirwell/tree/main/examples/theme-package) exercises this boundary
 from packed distributions rather than repository source aliases. The
-[i18n example](examples/i18n) separately demonstrates theme-owned localization.
+[i18n example](https://github.com/vp-tw/dirwell/tree/main/examples/i18n) separately demonstrates theme-owned localization.
 
 ## Public surface
 
@@ -60,5 +60,5 @@ selected alpha version.
 `pnpm verify:package` packs Dirwell and this private theme separately, installs
 them into a fresh project, and exercises their public imports. It verifies the
 CLI, an external renderer with SSG/MPA assets and encoded names, public types,
-and a real Rollup build. Successful local tarball consumption does not prove npm
+a real Rollup build, and an async CommonJS webpack build. Successful local tarball consumption does not prove npm
 publication or a registry install; release readback must verify those separately.

package/THEMING.md

@@ -9,7 +9,7 @@ behavior. Choose one of three paths:
 | Publish a basic no-script list                      | `createPlainTheme()`                      | Prepared entries and safe links |
 | Replace the full page                               | An `ExplorerTheme` with `render(context)` | Prepared entries and safe links |
 
-The [theme guide](docs/src/content/docs/themes.md) lists every default-theme
+The [theme guide](https://vp-tw.github.io/dirwell/themes/) lists every default-theme
 option, its accepted input, default, result, and use case. This file describes
 the component contract for theme authors.
 
@@ -46,20 +46,20 @@ export default defineConfig({
 ```
 
 Global search is progressive: the browser requests the generated JSON index
-only after the user selects `Everywhere`. Sorting and search controls can be
+only after the user opens Search all files and types a query. Sorting and search controls can be
 disabled independently without changing the component override API.
 
 Replacing `EntryList` or `EntryRow` disables the default MPA virtual list.
 Keep those defaults for large directories unless the replacement provides its
 own row loading. `virtualizeAfter` defaults to 500 entries.
 
-Within the bundled theme, the five select controls share a private renderer,
+Within the bundled theme, select controls share a private renderer,
 and `--dw-control-height` gives search, select, sort, and color-scheme controls
 one height. This is a default-theme styling hook, not a requirement for custom
 themes. The controls keep their native `input`, `select`, `details`, and
 `fieldset` semantics; override `Toolbar` to replace their markup.
 
-The bundled explorer has its own [design specification](src/theme-default/DESIGN.md)
+The bundled explorer has its own [design specification](https://github.com/vp-tw/dirwell/blob/main/src/theme-default/DESIGN.md)
 beside its components and styles. The repository-root `DESIGN.md` describes the
 official site; neither document constrains third-party themes.
 
@@ -73,8 +73,8 @@ Escape untrusted file names with the exported `escapeHtml` helper.
 
 The full `ExplorerTheme` contract can host a Svelte, Astro, React, or other SSR
 adapter that returns a complete HTML string and optional assets. The
-[`custom-theme`](examples/custom-theme) example builds a release catalog with
-its own HTML and CSS. The [`default-theme-override`](examples/default-theme-override)
+[`custom-theme`](https://github.com/vp-tw/dirwell/tree/main/examples/custom-theme) example builds a release catalog with
+its own HTML and CSS. The [`default-theme-override`](https://github.com/vp-tw/dirwell/tree/main/examples/default-theme-override)
 example keeps the default explorer and changes components, Catppuccin colors,
 and file icons. `createDefaultTheme({ icons })` accepts light and optional dark
 SVG sets, including fallbacks and extension mappings. Dirwell uses the same icon
@@ -85,4 +85,4 @@ set for static, global-search, and virtualized rows.
 An external package can return `ExplorerTheme` through its own factory and own
 its HTML, assets, styles, options, and localization. Pin the tested Dirwell alpha
 in its peer dependency. See [the package contract](THEME_PACKAGE_CONTRACT.md)
-and [the separately packed example](examples/theme-package).
+and [the separately packed example](https://github.com/vp-tw/dirwell/tree/main/examples/theme-package).

package/THIRD_PARTY_NOTICES.md

@@ -10,5 +10,5 @@ their respective owners. No endorsement is implied.
 The exact icon list is in [`dist/vscode-icons/NOTICE.txt`](./dist/vscode-icons/NOTICE.txt)
 in the published package, and in `src/vscode-icons/NOTICE.txt` in the source tree.
 Generated sites include this notice as `vscode-icons-NOTICE.txt`. The default
-theme footer links to the [Ledger theme README](./src/theme-default/README.md),
+theme footer links to the [Ledger theme README](https://github.com/vp-tw/dirwell/blob/main/src/theme-default/README.md),
 which links to the source notice.

package/dist/bin.mjs

@@ -97,7 +97,7 @@ async function stopDaemon(cwd) {
 }
 //#endregion
 //#region package.json
-var version = "0.1.0-alpha.1";
+var version = "0.1.0-alpha.3";
 //#endregion
 //#region src/cli.ts
 const commonArguments = {

package/dist/bun.d.mts

@@ -1,4 +1,4 @@
-import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-CKRUCTgW.mjs";
+import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-BEWhmsTM.mjs";
 import { UnpluginInstance } from "unplugin";
 //#region src/bun.d.ts
 declare const plugin: UnpluginInstance<DirwellPluginInput, true>["bun"];

package/dist/bun.mjs

@@ -1,4 +1,4 @@
-import { t as unplugin } from "./unplugin-p6AXhL4F.mjs";
+import { t as unplugin } from "./unplugin-3KZVc7em.mjs";
 //#region src/bun.ts
 const plugin = unplugin.bun;
 //#endregion

package/dist/{config-BJG2Zc3Q.d.mts → config-CJutlaP0.d.mts}

@@ -1,4 +1,4 @@
-import { p as SortOptions, r as ExplorerTheme, s as GenerateOptions } from "./model-CWjYM17j.mjs";
+import { p as SortOptions, r as ExplorerTheme, s as GenerateOptions } from "./model-D5PPrgIs.mjs";
 //#region src/config.d.ts
 interface DirwellConfig {
   readonly base?: string;
@@ -31,4 +31,4 @@ declare function loadDirwellConfig(cwd: string, command: DirwellConfigContext["c
 declare function resolveGenerateOptions(cwd: string, config: DirwellConfig, overrides?: Partial<Pick<DirwellConfig, "base" | "mode" | "outDir" | "root" | "urls">>): GenerateOptions;
 //#endregion
 export { loadDirwellConfig as a, defineConfig as i, DirwellConfigContext as n, resolveGenerateOptions as o, DirwellConfigInput as r, DirwellConfig as t };
-//# sourceMappingURL=config-BJG2Zc3Q.d.mts.map
+//# sourceMappingURL=config-CJutlaP0.d.mts.map

package/dist/esbuild.d.mts

@@ -1,4 +1,4 @@
-import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-CKRUCTgW.mjs";
+import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-BEWhmsTM.mjs";
 import { UnpluginInstance } from "unplugin";
 //#region src/esbuild.d.ts
 declare const plugin: UnpluginInstance<DirwellPluginInput, true>["esbuild"];

package/dist/esbuild.mjs

@@ -1,4 +1,4 @@
-import { t as unplugin } from "./unplugin-p6AXhL4F.mjs";
+import { t as unplugin } from "./unplugin-3KZVc7em.mjs";
 //#region src/esbuild.ts
 const plugin = unplugin.esbuild;
 //#endregion

package/dist/farm.d.mts

@@ -1,4 +1,4 @@
-import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-CKRUCTgW.mjs";
+import { n as DirwellPluginOptions, t as DirwellPluginInput } from "./unplugin-BEWhmsTM.mjs";
 import { UnpluginInstance } from "unplugin";
 //#region src/farm.d.ts
 declare const plugin: UnpluginInstance<DirwellPluginInput, true>["farm"];

package/dist/farm.mjs

@@ -1,4 +1,4 @@
-import { t as unplugin } from "./unplugin-p6AXhL4F.mjs";
+import { t as unplugin } from "./unplugin-3KZVc7em.mjs";
 //#region src/farm.ts
 const plugin = unplugin.farm;
 //#endregion