@vp-tw/dirwell 0.0.0-stage → 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @vp-tw/dirwell
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- 9f2fdce: Initial alpha release with the CLI, SSG/MPA generation, safe symlink handling, source filters, Ledger and Plain themes, all Unplugin build hosts, and typed rendering APIs. Includes a theme-owned English, Traditional Chinese, and Japanese example and concise local dates with exact-time disclosure.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dirwell contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# Dirwell
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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.
+
+## Quick start
+
+```bash
+pnpm install
+pnpm dirwell serve ./fixture
+pnpm dirwell build ./fixture -o ./generated
+```
+
+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
+```
+
+## Configuration
+
+Create `dirwell.config.ts` when a field has no CLI flag or you want a reusable
+setup:
+
+```ts
+import { defineConfig } from "@vp-tw/dirwell";
+
+export default defineConfig({
+  mode: "mpa",
+  base: "/downloads/",
+  urls: "base",
+  include: ["**/*.md", "assets/**"],
+  exclude: ["drafts/**"],
+});
+```
+
+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.
+
+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>`.
+
+## Output modes
+
+- `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.
+
+`__dirwell/` is reserved in both modes for generated assets such as broken-link
+raw views.
+
+## Vite integration
+
+The `@vp-tw/dirwell/vite` adapter builds one or more explorers alongside a Vite
+application and serves them through Vite's development server:
+
+```ts
+import { defineConfig } from "vite";
+import Dirwell from "@vp-tw/dirwell/vite";
+
+export default defineConfig({
+  plugins: [
+    Dirwell([
+      { root: "./docs", outDir: "dist/docs" },
+      { root: "./downloads", outDir: "dist/downloads", mode: "mpa" },
+    ]),
+  ],
+});
+```
+
+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
+
+```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
+```
+
+Dirwell is MIT licensed.

package/THEME_PACKAGE_CONTRACT.md

@@ -0,0 +1,64 @@
+# Alpha theme package contract
+
+An independent theme package exports a factory returning `ExplorerTheme` from
+`@vp-tw/dirwell`. Consumers import that factory in `dirwell.config.ts`. Complete
+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
+from packed distributions rather than repository source aliases. The
+[i18n example](examples/i18n) separately demonstrates theme-owned localization.
+
+## Public surface
+
+| Surface                  | Contract                                                                                                               |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| `ExplorerTheme`          | A name, optional `searchIndex`, and a synchronous or asynchronous `render(context)` function.                          |
+| `ThemeContext`           | Prepared `DirectoryData`, output mode/name, sort policy, optional HTML base, asset/index URLs, and navigation helpers. |
+| `RenderedPage`           | A complete HTML document and optional map of safe asset filenames to strings or bytes.                                 |
+| Default theme components | Optional typed overrides and ordered layers from `@vp-tw/dirwell/theme`; a full renderer can operate independently.    |
+
+Use `hrefFor()`, `hrefForDirectory()`, and `exitsExplorerFor()` instead of
+reconstructing filesystem or deployment URLs. `hrefFor()` can return `null`;
+render an unavailable label in that case. Preserve the caller's HTML base when
+`documentBaseHref` is present.
+
+Set `searchIndex: false` when the theme has no global search. Otherwise the
+generator can emit index assets, but the theme still owns how they are used.
+Styles and tokens remain private to each renderer. Core does not supply a locale
+setting; Ledger and Plain keep their English interfaces.
+
+## Assets and trust
+
+The generator validates asset filenames and deploys them beside each SSG page
+or in the shared MPA `__dirwell/` directory. Refer to them with `assetHref()`.
+For MPA, every use of the same asset filename must provide identical bytes;
+conflicting shared assets fail the build. Choose names that do not collide with
+selected source files, generated page names, or other theme assets.
+
+Theme packages execute as trusted Node code. Rendering needs prepared source
+data rather than a second source-tree traversal; packages may load their own
+bundled styles/assets. Treat entry names, declared symlink targets, and visible
+paths as untrusted text and escape them before HTML insertion. Avoid serializing
+machine-absolute `absolutePath` or `resolvedPath` into browser output. A theme
+owns its asset licenses and notices.
+
+## Alpha compatibility
+
+Pin the exact Dirwell alpha used by the theme's tests in `peerDependencies`.
+Retest before widening that range or accepting another alpha; this contract is
+not a stable API promise. Public types and component contracts may evolve before
+stable. Consumers own the decision to upgrade their Dirwell/theme pair.
+
+The proof package deliberately replaces the full renderer. Component overrides
+remain supported, but their authors must also verify the default runtime's DOM
+expectations, keyboard behavior, virtualization, and theme assets against their
+selected alpha version.
+
+## Consumer verification
+
+`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
+publication or a registry install; release readback must verify those separately.

package/THEMING.md

@@ -0,0 +1,88 @@
+# Theme architecture
+
+Dirwell themes own the complete document, styles, icons, and optional browser
+behavior. Choose one of three paths:
+
+| Need                                                | Use                                       | Keep                            |
+| --------------------------------------------------- | ----------------------------------------- | ------------------------------- |
+| Change controls, colors, icons, or a few HTML parts | `createDefaultTheme(options)`             | Default explorer behavior       |
+| 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
+option, its accepted input, default, result, and use case. This file describes
+the component contract for theme authors.
+
+## Component layers
+
+Use an `ExplorerTheme` to replace the complete renderer. Use component layers
+to replace selected parts of the default theme: `PageShell`, `Breadcrumbs`,
+`Toolbar`, `EntryList`, `EntryRow`, `EmptyState`, `Footer`, and
+`Icon`.
+
+Each component is a typed function from props to HTML. Pass one override object
+or an array of layers. Later layers win when they define the same component:
+
+```ts
+import { createDefaultTheme, defineConfig } from "@vp-tw/dirwell";
+
+export default defineConfig({
+  theme: createDefaultTheme({
+    globalSearch: true,
+    sorting: true,
+    project: {
+      author: "Your name",
+      authorUrl: "https://github.com/you",
+      repositoryUrl: "https://github.com/you/project",
+      license: "MIT License",
+      licenseUrl: "https://github.com/you/project/blob/main/LICENSE",
+    },
+    components: {
+      Footer: ({ parentHref }) =>
+        parentHref === null ? "<footer>Home</footer>" : "<footer>Nested</footer>",
+    },
+  }),
+});
+```
+
+Global search is progressive: the browser requests the generated JSON index
+only after the user selects `Everywhere`. 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,
+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)
+beside its components and styles. The repository-root `DESIGN.md` describes the
+official site; neither document constrains third-party themes.
+
+Default components are exported as `defaultThemeComponents`, so a replacement
+can wrap one explicitly. This provides the useful part of Docusaurus swizzling
+without virtual aliases or unsafe component categories.
+
+Component props and names are public API. Components receive prepared
+filesystem data and navigation decisions; they do not read the filesystem.
+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)
+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
+set for static, global-search, and virtualized rows.
+
+## Independent alpha packages
+
+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).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,14 @@
+# Third-party notices
+
+Dirwell's code is MIT-licensed. The default theme includes selected icons from
+[vscode-icons](https://github.com/vscode-icons/vscode-icons/tree/6b4471cf8dcdeafc9d1203f9156d285fc3e9d552/icons).
+The icons are licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
+and are attributed to the vscode-icons contributors. They are redistributed
+without modification. Branded icons may carry additional rights belonging to
+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),
+which links to the source notice.

package/dist/bin.d.mts

@@ -0,0 +1 @@
+export {}