@peisar/peisar-wasm32-wasi 0.3.11 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peisar/peisar-wasm32-wasi",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "main": "peisar.wasi.cjs",
   "files": [
     "peisar.wasm32-wasi.wasm",

package/peisar.wasi-browser.js

@@ -1443,4 +1443,5 @@ export default __napiModule.exports
 export const Peisar = __napiModule.exports.Peisar
 export const PeisarCache = __napiModule.exports.PeisarCache
 export const frontmatter = __napiModule.exports.frontmatter
+export const HostingProvider = __napiModule.exports.HostingProvider
 export const yamlParser = __napiModule.exports.yamlParser

package/peisar.wasi.cjs

@@ -1,4 +1,4 @@
-// napi-rs-artifact-metadata:{"version":2,"rootEntry":"index.cjs","exports":["Peisar","PeisarCache","frontmatter","yamlParser"],"managedRootEntries":["browser.js","index.cjs","peisar.wasm","peisar.debug.wasm"]}
+// napi-rs-artifact-metadata:{"version":2,"rootEntry":"index.cjs","exports":["Peisar","PeisarCache","frontmatter","HostingProvider","yamlParser"],"managedRootEntries":["browser.js","index.cjs","peisar.wasm","peisar.debug.wasm"]}
 /* eslint-disable */
 /* auto-generated by NAPI-RS */
 
@@ -2300,4 +2300,5 @@ module.exports = __napiModule.exports
 module.exports.Peisar = __napiModule.exports.Peisar
 module.exports.PeisarCache = __napiModule.exports.PeisarCache
 module.exports.frontmatter = __napiModule.exports.frontmatter
+module.exports.HostingProvider = __napiModule.exports.HostingProvider
 module.exports.yamlParser = __napiModule.exports.yamlParser

package/peisar.wasi.d.cts

@@ -1,7 +1,3 @@
-export type PeisarEmphasisLevel = "Italic" | "Bold";
-export type PeisarTableCellAlignment = "Default" | "Left" | "Center" | "Right";
-export type PeisarTableCellAlignments = PeisarTableCellAlignment[];
-export type PeisarTaskState = "Unchecked" | "Checked";
 
 /** The WASI flavor this loader instantiates. */
 export declare const __napiBindingTarget: 'wasm32-wasi'
@@ -68,51 +64,116 @@ export declare class Peisar {
 }
 
 /**
- * In-memory cache of the Markdown and asset files under a directory tree.
+ * In-memory + archive-backed cache of the Markdown and asset files under a
+ * directory tree.
  *
- * The cache maps absolute source paths to [`CachedContent`] entries, is
- * mirrored to a `.peisar_cache` directory on disk, and — after
- * [`PeisarCache::start_watching`] — tracks the source directories with a
- * recursive file watcher.
- *
- * Rust consumers read the cache with [`PeisarCache::get`] and
- * [`PeisarCache::all`]; JavaScript consumers use the N-API methods below
- * (`getText`, `getBinary`, `listFiles`, `markdownFiles`, `assetFiles`, …).
+ * Memory is the source of truth for hot content; a background worker
+ * flushes a binary shard archive to `.peisar-cache` for cold/large
+ * entries, front-ended by the `map.json` search index. Watchers keep the
+ * memory tier in sync with the filesystem.
  */
 export declare class PeisarCache {
   /**
-   * Construct a new PeisarCache using the default discovery behavior.
+   * JS: `new PeisarCache(entryDir, assetsDir?, options?)`.
    *
-   * JS: `new PeisarCache(entryDir, assetsDir?)` — both plain strings.
+   * `options` configures markdown parsing (`fragment`, GFM, …), archive
+   * thresholds, hosting resolution, and the output directory. Custom
+   * visitors/parsers register afterwards via `useVisitor` /
+   * `useParser`.
+   */
+  constructor(entryDir: string, assetsDir?: string | undefined | null, options?: PeisarCacheJsOptions | undefined | null)
+  /**
+   * JS: `PeisarCache.withConfigJs(config)` — full configuration form,
+   * including memory-tier budgets.
    */
-  constructor(entryDir: string, assetsDir?: string | undefined | null)
+  static withConfigJs(config: PeisarCacheConfig): PeisarCache
+  /**
+   * Register a JavaScript AST visitor applied to every page render
+   * (JS: `cache.useVisitor({ visitBlock, visitInline })`).
+   */
+  useVisitor(visitor: Visitor): void
   /**
-   * JS: same as the constructor, for callers that prefer a factory shape.
-   * Kept non-generic so NAPI can export it.
+   * Register a JavaScript parser hook applied to every page render
+   * (JS: `cache.useParser({ parseBlock, parseInline })`).
    */
-  static withConfigJs(entryDir: string, assetsDir?: string | undefined | null): PeisarCache
+  useParser(parser: Parser): void
   /**
    * JS: `cache.startWatchingJs()` — start watching the entry (and
    * assets) directories recursively; errors surface as JS exceptions.
    */
   startWatchingJs(): void
   /**
-   * ----------------------------------------------------------------
-   * JavaScript (NAPI) surface
-   * ----------------------------------------------------------------
-   * All JS methods take/return plain strings because `&Path`/`PathBuf`
-   * do not cross the NAPI boundary.
-   * JS: `cache.getText(absPath)` — cached text of a file, or null.
+   * JS: `cache.getText(absPath)` — cached text of a file, or `null`.
+   * Reads fall through to the archive tier for evicted entries.
    */
   getText(absPath: string): string | null
-  /** JS: `cache.getBinary(absPath)` — cached bytes of a binary asset, or null. */
+  /**
+   * JS: `cache.getBinary(absPath)` — cached bytes of a binary asset, or
+   * `null`. Reads fall through to the archive tier.
+   */
   getBinary(absPath: string): Array<number> | null
-  /** JS: `cache.listFiles()` — absolute paths of everything cached. */
+  /**
+   * JS: `cache.listFiles()` — absolute paths of everything cached
+   * (memory + archive tiers).
+   */
   listFiles(): Array<string>
-  /** JS: `cache.markdownFiles()` — absolute paths of cached markdown files. */
+  /**
+   * JS: `cache.markdownFiles()` — absolute paths of cached markdown
+   * files (either tier).
+   */
   markdownFiles(): Array<string>
-  /** JS: `cache.assetFiles()` — absolute paths of cached non-markdown files. */
+  /**
+   * JS: `cache.assetFiles()` — absolute paths of cached non-markdown
+   * files (either tier).
+   */
   assetFiles(): Array<string>
+  /**
+   * JS: `cache.pages()` — every page object, for Liquid themes
+   * (`{{ page.title }}`, `{{ page.layout }}`, …).
+   */
+  pages(): Array<PageObject>
+  /**
+   * JS: `cache.getPage(inputPath)` — a single page object by absolute
+   * input path, or `null`.
+   */
+  getPage(inputPath: string): PageObject | null
+  /** JS: `cache.assets()` — every asset object. */
+  assets(): Array<AssetsObject>
+  /**
+   * JS: `cache.getAsset(inputPath)` — a single asset object by absolute
+   * input path, or `null`.
+   */
+  getAsset(inputPath: string): AssetsObject | null
+  /**
+   * JS: `cache.archived()` — absolute paths flushed to the disk
+   * archive. Everything not listed still lives in memory only.
+   */
+  archived(): Array<string>
+  /**
+   * JS: `cache.mapJson()` — the current `map.json` document (path →
+   * shard location + metadata, including front matter for search).
+   */
+  mapJson(): string
+  /**
+   * JS: `cache.flush()` — write all pending archive entries now,
+   * blocking until the worker is done.
+   */
+  flush(): void
+  /**
+   * JS: `cache.baseUrl()` — the resolved base URL path prefix for the
+   * configured hosting (e.g. `/repo/` for a GitHub Pages project site).
+   */
+  baseUrl(): string
+  /**
+   * JS: `cache.resolveUrl(path)` — prefix a site-relative path with the
+   * resolved base URL: `resolveUrl("docs/intro")` → `/repo/docs/intro`.
+   */
+  resolveUrl(path: string): string
+  /**
+   * JS: `cache.siteUrl()` — absolute origin URL for canonical URLs, or
+   * `null` when not configured.
+   */
+  siteUrl(): string | null
   /**
    * JS: `cache.onChange(cb)` — invoke `cb(event)` on every file change the
    * watcher detects while watching is active. Returns a subscription id
@@ -125,15 +186,50 @@ export declare class PeisarCache {
   /** JS: `cache.offChange(id)` — remove a previously registered callback. */
   offChange(id: number): void
   /**
-   * JS: `cache.dispose()` — stop the watcher and drop JS change callbacks.
-   * Safe to call more than once.
+   * JS: `cache.dispose()` — stop the watcher, flush pending archive
+   * writes, and drop JS change callbacks. Safe to call more than once.
    *
    * Rust consumers do not need this: dropping the [`PeisarCache`] stops
-   * the watcher, closes the persistence channel, and joins the worker.
+   * the watcher, flushes the archive, and joins the workers.
    */
   dispose(): void
 }
 
+/** Flush thresholds for the disk-archive tier. */
+export interface ArchiveConfig {
+  /**
+   * Pending-content threshold (bytes) that triggers writing a new
+   * shard; `0` disables size-based flushing (interval/drop only).
+   */
+  shardBytes?: number
+  /**
+   * Maximum time (ms) pending entries may sit in the worker buffer
+   * before being flushed. `0` disables the timer.
+   */
+  flushIntervalMs?: number
+}
+
+/** An asset mirrored by the cache (JS/CSS/image/video/font/…). */
+export interface AssetsObject {
+  /** File name without extension (`foo.png` → `foo`). */
+  fileName: string
+  /** URL for the asset (`path/to/foo.png` → `/path/to/foo.png`). */
+  slug: string
+  /** Raw content: UTF-8 text for textual assets, base64 for binaries. */
+  raw: string
+  /** Build output path for the asset. */
+  outFilePath: string
+  /** Original absolute source path (watch-process identity). */
+  inputFilePath: string
+  /** File extension (lowercase, without dot). */
+  ext: string
+  /**
+   * Kind classification: `"Js"`, `"Css"`, `"Image"`, `"Video"`,
+   * `"Font"`, or `"Other"`.
+   */
+  fileType: string
+}
+
 /**
  * Options that control how Markdown is parsed.
  *
@@ -170,6 +266,27 @@ export interface Attributes {
   attributes?: Array<[string, string]>
 }
 
+/**
+ * Resolved hosting configuration: the single source of truth for every
+ * URL the pipeline emits (page slugs, asset links, absolute URLs).
+ */
+export interface BaseDirInfo {
+  /** Hosting provider in effect. */
+  provider: HostingProvider
+  /** Repository name (GitHub Pages project sites): `/<repo>/` prefix. */
+  repo?: string
+  /**
+   * Custom site URL (`https://example.com` or `https://user.github.io/repo`).
+   * Used verbatim as the URL root for [`Self::site_url`].
+   */
+  siteUrl?: string
+  /**
+   * Extra path prefix under the host (e.g. `subpath` for
+   * `example.com/subpath/`).
+   */
+  pathPrefix?: string
+}
+
 /** Block-level nodes. */
 export type Block =
   | { type: 'Heading'; /** Heading level (1–6). */
@@ -270,7 +387,8 @@ export interface CacheChangeEvent {
 /**
  * An entry stored in the cache: raw UTF-8 text (markdown and textual
  * assets) or raw bytes (binary assets). Exposed to JavaScript so JS
- * consumers can branch on the variant.
+ * consumers can branch on the variant. The serde derives back the
+ * bincode round-trip through the disk archive.
  */
 export type CachedContent =
   | { type: 'Text'; field0: string }
@@ -305,6 +423,36 @@ export interface FrontmatterResult {
   yamlData?: Record<string, any>
 }
 
+/** Static-hosting configuration for baseUrl resolution. */
+export interface HostingConfig {
+  /** Hosting provider (see [`HostingProvider`]). */
+  provider?: HostingProvider
+  /** GitHub repository name for project pages (`/<repo>/` prefix). */
+  repo?: string
+  /** Custom site URL (overrides provider defaults when set). */
+  siteUrl?: string
+  /** Extra path prefix (e.g. `"subpath"` for `example.com/subpath/`). */
+  pathPrefix?: string
+}
+
+/** Static site hosting providers with known `baseUrl` behavior. */
+export declare const enum HostingProvider {
+  /**
+   * GitHub Pages. User/org sites (`<user>.github.io`) serve at `/`;
+   * project sites at `/<repo>`. Pass the repository name via
+   * `repo` to get the `/<repo>/` prefix.
+   */
+  GithubPages = 'GithubPages',
+  /** Vercel: always `/` (subpath deployments use rewrites, not paths). */
+  Vercel = 'Vercel',
+  /** Netlify: always `/`. */
+  Netlify = 'Netlify',
+  /** Cloudflare Pages: always `/`. */
+  CloudflarePages = 'CloudflarePages',
+  /** Self-hosted or custom setup: use the `site_base_url` string as given. */
+  Custom = 'Custom',
+}
+
 /** Inline-level nodes. */
 export type Inline =
   | { type: 'Text'; /** The text value. */
@@ -423,6 +571,59 @@ export interface ListItem {
   pos: Span
 }
 
+/** LRU budgets for the memory tier. */
+export interface MemoryConfig {
+  /**
+   * Maximum total bytes of raw content kept in memory (`0` =
+   * unlimited). When the budget is exceeded, the least recently used
+   * entries are evicted (they remain readable from the disk archive).
+   */
+  byteBudget?: number
+  /** Maximum number of entries in memory (`0` = unlimited). */
+  entryBudget?: number
+}
+
+/**
+ * A page rendered for a Liquid theme: front-matter fields flattened next
+ * to pipeline-derived fields (layout, slug, html, …).
+ */
+export interface PageObject {
+  /**
+   * Layout name from front matter (e.g. `default`, `page`, `post`);
+   * `"default"` when front matter does not set one.
+   */
+  layout: string
+  /**
+   * File name without extension (`foo.md` → `foo`); `index` for
+   * directory roots. Used as a search / lookup key.
+   */
+  fileName: string
+  /** Request URL for the page (`path/to/foo.md` → `/path/to/foo`). */
+  slug: string
+  /** HTML rendered from the markdown by Peisar. */
+  html: string
+  /**
+   * Build output path (`path/to/foo.md` → `outDir/path/to/foo/index.html`),
+   * relative to the output root unless absolute.
+   */
+  outFilePath: string
+  /** Original absolute source path (watch-process identity). */
+  inputFilePath: string
+  /** Page title (from front matter, or the first `#` heading). */
+  title?: string
+  /** Short description from front matter. */
+  summary?: string
+  /** Category tags from front matter. */
+  tags?: Array<string>
+  /** Publication date from front matter (string form `yyyy-mm-dd`). */
+  publishDate?: string
+  /**
+   * Any extra front-matter keys not mapped to a named field, exposed
+   * verbatim (as strings) so themes can render `{{ page.custom }}`.
+   */
+  extra?: Record<string, string>
+}
+
 /** Either property may be omitted / `null` to skip that phase. */
 export interface Parser {
   /** Optional JS block parser hook (JS: `parseBlock`). */
@@ -431,6 +632,59 @@ export interface Parser {
   parseInline?: InlineParseCallback
 }
 
+/**
+ * Cache-wide configuration: directories, markdown options, memory/archive
+ * budgets, hosting/baseUrl resolution, and the build output directory.
+ */
+export interface PeisarCacheConfig {
+  /**
+   * Entry directory holding the markdown files (absolute, or relative
+   * to the current working directory).
+   */
+  entryDir: string
+  /**
+   * Optional assets directory (defaults to `public` under the cwd when
+   * omitted).
+   */
+  assetsDir?: string
+  /**
+   * Markdown parsing/rendering options applied to every page render
+   * (GFM/Kramdown toggles, `fragment`, title, …). Custom visitors and
+   * parsers are registered separately via `useVisitor` / `useParser`.
+   */
+  markdown?: PeisarOptions
+  /**
+   * Memory-tier budgets (LRU eviction). Defaults: 64 MiB bytes,
+   * unlimited entries.
+   */
+  memory?: MemoryConfig
+  /** Disk-archive tier thresholds. Defaults: 8 MiB shards, 2 s flush. */
+  archive?: ArchiveConfig
+  /** Static-hosting baseUrl resolution (GitHub Pages/Vercel/…). */
+  hosting?: HostingConfig
+  /**
+   * Build output directory used for `outFilePath` fields (default
+   * `".peisar"`).
+   */
+  outDir?: string
+}
+
+/**
+ * JS-side options accepted by the `PeisarCache` constructor (a flattened
+ * subset of [`PeisarCacheConfig`]; memory budgets only apply through the
+ * `withConfig` factory).
+ */
+export interface PeisarCacheJsOptions {
+  /** Markdown parsing/rendering options (`fragment`, GFM, …). */
+  markdown?: PeisarOptions
+  /** Disk-archive thresholds (shard size / flush interval). */
+  archive?: ArchiveConfig
+  /** Static-hosting baseUrl resolution. */
+  hosting?: HostingConfig
+  /** Build output directory. */
+  outDir?: string
+}
+
 /**
  * JavaScript options for Markdown parsing and HTML rendering.
  *