@markii/host 0.0.1 → 0.17.0-next.2

package/dist/export/cascade.d.ts

@@ -0,0 +1,98 @@
+import type { NoteLink } from './note-links.js';
+/**
+ * How far from the root note a cascade follows links. Four hops covers the
+ * shapes people actually build, an index note pointing at sections that
+ * point at pages, without turning one command into a whole-vault export.
+ */
+export declare const DEFAULT_CASCADE_MAX_DEPTH = 4;
+/**
+ * How many notes one cascade may export. A second, independent guard: a
+ * shallow graph can still be enormously wide, and an archive of a hundred
+ * pages is already past what anyone meant by "this note and what it links
+ * to".
+ */
+export declare const DEFAULT_CASCADE_MAX_NOTES = 100;
+/** One note the walk reached. */
+export interface CascadeNote {
+    /** The note's own path, in whatever form the host resolves and reads. */
+    readonly path: string;
+    /** The note's full source text. */
+    readonly text: string;
+    /** Hops from the root note. The root itself is 0. */
+    readonly depth: number;
+}
+/** Reads one note's text, or reports that it could not be read. A reader that throws is treated as unreadable. */
+export type CascadeNoteReader = (path: string) => Promise<string | undefined> | string | undefined;
+/**
+ * Resolves one link, as written in `fromNotePath`, to the path of a note in
+ * this vault or workspace, or `undefined` when it names something that is
+ * not a note here. This is where a host puts its own resolution rules: an
+ * Obsidian vault resolves a bare note name from anywhere, a folder-relative
+ * host resolves against the linking note's folder.
+ */
+export type CascadeLinkResolver = (link: NoteLink, fromNotePath: string) => string | undefined;
+/** Why a walk stopped early. */
+export type CascadeTruncation = 'depth' | 'count';
+export interface CascadeWalkOptions {
+    /** The note the cascade starts from. */
+    readonly rootPath: string;
+    readonly readNote: CascadeNoteReader;
+    readonly resolveLink: CascadeLinkResolver;
+    /** Defaults to `DEFAULT_CASCADE_MAX_DEPTH`. */
+    readonly maxDepth?: number;
+    /** Defaults to `DEFAULT_CASCADE_MAX_NOTES`. */
+    readonly maxNotes?: number;
+}
+export interface CascadeWalkResult {
+    /** Every note reached, breadth first, the root note always first. */
+    readonly notes: readonly CascadeNote[];
+    /** Links that resolved to a note the reader could not read, for the diagnostics surface. */
+    readonly unreadable: readonly {
+        readonly path: string;
+        readonly from: string;
+    }[];
+    /** Set when a limit stopped the walk before it ran out of links to follow. */
+    readonly truncated?: CascadeTruncation;
+}
+/**
+ * Walks the note graph out from `rootPath`, breadth first, and returns
+ * every note it reached.
+ *
+ * Breadth first rather than depth first on purpose: when a limit cuts the
+ * walk short, what survives is everything CLOSE to the root, which is what
+ * a reader of the root note actually needs.
+ *
+ * Never throws. A note that cannot be read is recorded and skipped, and a
+ * root note that cannot be read simply produces an empty walk, which the
+ * caller reports as having nothing to export.
+ */
+export declare function walkNoteCascade(options: CascadeWalkOptions): Promise<CascadeWalkResult>;
+/**
+ * The archive entry name a cascade's own index page uses. Reserved up
+ * front with `assignCascadeFileNames`'s `reservedNames`, so a walked note
+ * that happens to be called `index` gets a numeric suffix instead of
+ * silently colliding with, and overwriting, the index page in the zip.
+ */
+export declare const CASCADE_INDEX_FILE_NAME = "index.html";
+/**
+ * The file name each note gets inside the archive: its own base name with
+ * an `.html` extension.
+ *
+ * The archive is flat, so two notes in different folders can want the same
+ * name. The first one to be reached keeps it, and each later claimant gets
+ * a numeric suffix. The walk is breadth first and deterministic, so the
+ * same vault always produces the same names.
+ *
+ * `reservedNames` are claimed before any note, case-insensitively, exactly
+ * like an earlier note's claim — a host builds the same archive's index
+ * page under one of these names and needs it to never collide with a
+ * walked note.
+ */
+export declare function assignCascadeFileNames(paths: readonly string[], reservedNames?: Iterable<string>): Map<string, string>;
+/**
+ * One note's text with every link to another note IN THIS CASCADE pointed
+ * at that note's exported file. A link to anything else, a note outside the
+ * walked set or a file that is not a note at all, is left exactly as the
+ * author wrote it.
+ */
+export declare function rewriteCascadeLinks(note: CascadeNote, fileNames: ReadonlyMap<string, string>, resolveLink: CascadeLinkResolver): string;

package/dist/export/cascade.js

@@ -0,0 +1,159 @@
+/**
+ * The cascade export's pure half (GitHub issue #28 slice 3, part 2):
+ * walking the notes one note links to, deciding what each exported file is
+ * called, and rewriting the links between them so the exported set is
+ * navigable on its own.
+ *
+ * PURE AND HOST-NEUTRAL, like `./note-links.ts` beside it. Reading a note
+ * and resolving a link target to a real note are injected, because only a
+ * host knows what a vault or a workspace contains. Obsidian is the first
+ * caller (issue #28 slice 3); a VS Code cascade command would supply its
+ * own two functions and reuse everything here unchanged. Nothing in this
+ * file imports `node:*`, so it stays available to a browser bundle if a
+ * host ever needs it there.
+ *
+ * BOUNDED BY CONSTRUCTION. A note graph has cycles, and a vault can be
+ * enormous, so the walk carries three guards a caller cannot switch off:
+ * a visited set, a depth limit, and a note-count limit. Hitting a limit is
+ * not a failure. The walk stops, says which limit stopped it, and the host
+ * writes that to its diagnostics surface, per AGENTS.md's rule that a
+ * quiet outcome still has to be discoverable.
+ */
+import { extractNoteLinks, rewriteNoteLinks } from './note-links.js';
+import { exportBaseName } from './note-export.js';
+/**
+ * How far from the root note a cascade follows links. Four hops covers the
+ * shapes people actually build, an index note pointing at sections that
+ * point at pages, without turning one command into a whole-vault export.
+ */
+export const DEFAULT_CASCADE_MAX_DEPTH = 4;
+/**
+ * How many notes one cascade may export. A second, independent guard: a
+ * shallow graph can still be enormously wide, and an archive of a hundred
+ * pages is already past what anyone meant by "this note and what it links
+ * to".
+ */
+export const DEFAULT_CASCADE_MAX_NOTES = 100;
+/**
+ * Walks the note graph out from `rootPath`, breadth first, and returns
+ * every note it reached.
+ *
+ * Breadth first rather than depth first on purpose: when a limit cuts the
+ * walk short, what survives is everything CLOSE to the root, which is what
+ * a reader of the root note actually needs.
+ *
+ * Never throws. A note that cannot be read is recorded and skipped, and a
+ * root note that cannot be read simply produces an empty walk, which the
+ * caller reports as having nothing to export.
+ */
+export async function walkNoteCascade(options) {
+    const maxDepth = options.maxDepth ?? DEFAULT_CASCADE_MAX_DEPTH;
+    const maxNotes = options.maxNotes ?? DEFAULT_CASCADE_MAX_NOTES;
+    const notes = [];
+    const unreadable = [];
+    const visited = new Set();
+    let truncated;
+    const read = async (path) => {
+        try {
+            return await options.readNote(path);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const rootText = await read(options.rootPath);
+    if (rootText === undefined) {
+        return { notes: [], unreadable: [{ path: options.rootPath, from: '' }] };
+    }
+    visited.add(options.rootPath);
+    notes.push({ path: options.rootPath, text: rootText, depth: 0 });
+    for (let cursor = 0; cursor < notes.length; cursor += 1) {
+        const current = notes[cursor];
+        if (current.depth >= maxDepth) {
+            // Only a note that actually has an unfollowed link proves the depth
+            // limit changed the outcome, so the flag is set below rather than
+            // here.
+            const hasLink = extractNoteLinks(current.text).some((link) => options.resolveLink(link, current.path) !== undefined);
+            if (hasLink)
+                truncated ??= 'depth';
+            continue;
+        }
+        for (const link of extractNoteLinks(current.text)) {
+            const resolved = options.resolveLink(link, current.path);
+            if (resolved === undefined)
+                continue;
+            if (visited.has(resolved))
+                continue;
+            visited.add(resolved);
+            if (notes.length >= maxNotes) {
+                truncated ??= 'count';
+                continue;
+            }
+            const text = await read(resolved);
+            if (text === undefined) {
+                unreadable.push({ path: resolved, from: current.path });
+                continue;
+            }
+            notes.push({ path: resolved, text, depth: current.depth + 1 });
+        }
+    }
+    return {
+        notes,
+        unreadable,
+        ...(truncated !== undefined ? { truncated } : {}),
+    };
+}
+/**
+ * The archive entry name a cascade's own index page uses. Reserved up
+ * front with `assignCascadeFileNames`'s `reservedNames`, so a walked note
+ * that happens to be called `index` gets a numeric suffix instead of
+ * silently colliding with, and overwriting, the index page in the zip.
+ */
+export const CASCADE_INDEX_FILE_NAME = 'index.html';
+/**
+ * The file name each note gets inside the archive: its own base name with
+ * an `.html` extension.
+ *
+ * The archive is flat, so two notes in different folders can want the same
+ * name. The first one to be reached keeps it, and each later claimant gets
+ * a numeric suffix. The walk is breadth first and deterministic, so the
+ * same vault always produces the same names.
+ *
+ * `reservedNames` are claimed before any note, case-insensitively, exactly
+ * like an earlier note's claim — a host builds the same archive's index
+ * page under one of these names and needs it to never collide with a
+ * walked note.
+ */
+export function assignCascadeFileNames(paths, reservedNames = []) {
+    const names = new Map();
+    const taken = new Set();
+    for (const reserved of reservedNames) {
+        taken.add(reserved.toLowerCase());
+    }
+    for (const path of paths) {
+        const base = exportBaseName(path);
+        let candidate = `${base}.html`;
+        let counter = 2;
+        while (taken.has(candidate.toLowerCase())) {
+            candidate = `${base}-${String(counter)}.html`;
+            counter += 1;
+        }
+        taken.add(candidate.toLowerCase());
+        names.set(path, candidate);
+    }
+    return names;
+}
+/**
+ * One note's text with every link to another note IN THIS CASCADE pointed
+ * at that note's exported file. A link to anything else, a note outside the
+ * walked set or a file that is not a note at all, is left exactly as the
+ * author wrote it.
+ */
+export function rewriteCascadeLinks(note, fileNames, resolveLink) {
+    return rewriteNoteLinks(note.text, (link) => {
+        const resolved = resolveLink(link, note.path);
+        if (resolved === undefined)
+            return undefined;
+        return fileNames.get(resolved);
+    });
+}

package/dist/export/export-zip.d.ts

@@ -0,0 +1,19 @@
+/** One file in a cascade archive. */
+export interface ExportArchiveEntry {
+    /** The file's name inside the archive. Flat: no directories. */
+    readonly name: string;
+    /** The file's UTF-8 text. */
+    readonly text: string;
+}
+/**
+ * The archive bytes for `entries`.
+ *
+ * Deflate level 6, the ordinary default: exported HTML embeds base64 image
+ * data, which compresses poorly, while the markup around it compresses
+ * well, and level 6 is the balance every archiver picked for the same
+ * reason.
+ *
+ * `mtime` is deliberately not set, so the same set of notes always produces
+ * byte-identical output and a re-export is diffable.
+ */
+export declare function zipExportArchive(entries: readonly ExportArchiveEntry[]): Uint8Array;

package/dist/export/export-zip.js

@@ -0,0 +1,38 @@
+/**
+ * Packing a cascade export into one archive (GitHub issue #28 slice 3,
+ * part 2).
+ *
+ * WHY NOT `@markii/bundle`. That package's zip module is about `.mkz`
+ * bundles: reading one safely (entry-size guards, CRC checks, a path jail)
+ * and writing one back out with a manifest. A cascade archive is not a
+ * bundle. It has no manifest, no scripts, and no bundle semantics at all,
+ * so borrowing `exportZipBundle` would mean claiming a format this is not.
+ * What both share is `fflate`, an approved dependency, so this writes the
+ * archive directly and stays a dozen lines.
+ *
+ * Host-neutral and free of `node:*`: `fflate` and `TextEncoder` work in
+ * every environment either host runs in.
+ */
+import { zipSync } from 'fflate';
+/**
+ * The archive bytes for `entries`.
+ *
+ * Deflate level 6, the ordinary default: exported HTML embeds base64 image
+ * data, which compresses poorly, while the markup around it compresses
+ * well, and level 6 is the balance every archiver picked for the same
+ * reason.
+ *
+ * `mtime` is deliberately not set, so the same set of notes always produces
+ * byte-identical output and a re-export is diffable.
+ */
+export function zipExportArchive(entries) {
+    const encoder = new TextEncoder();
+    // A null-prototype object, matching how `@markii/bundle`'s own zip
+    // writing guards `zipSync`'s bracket assignment against a file named
+    // `__proto__`.
+    const files = Object.create(null);
+    for (const entry of entries) {
+        files[entry.name] = encoder.encode(entry.text);
+    }
+    return zipSync(files, { level: 6 });
+}

package/dist/export/image-embed.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Embedding a note's local images into its exported HTML (GitHub issue #28
+ * slice 3, part 1), so an exported file is genuinely self-contained: one
+ * document a user can mail, archive, or open on a machine that has never
+ * seen the vault, with its pictures still in it.
+ *
+ * WHERE THIS SITS. `./note-export.ts` composes an already-rendered body
+ * string into the export page. This module rewrites that body BEFORE the
+ * composition, turning every embeddable `<img src>` into a `data:` URI. It
+ * works on the rendered string rather than on the note's AST on purpose:
+ * the body is whatever engine rendered it, React or `@markii/html`, and a
+ * pack component's own images have to be embedded too. A string rewrite is
+ * the one place both engines and every component meet.
+ *
+ * WHAT STAYS A URL. Anything with a scheme, so `http:` and `https:` sources
+ * stay live URLs exactly as authored, and a `data:` URI is already
+ * embedded. A protocol-relative `//host/x.png` is a remote source too. Only
+ * a genuinely local, relative path is a candidate.
+ *
+ * THE HOST SEAM. This package knows nothing about vaults, workspace
+ * folders, or filesystems, so reading the bytes is injected: a host hands
+ * in an `ExportImageReader` that resolves a source the way its own preview
+ * resolves one and reads it, or reports that it could not. That keeps
+ * `@markii/host` free of host APIs while the size cap, the MIME rules, the
+ * base64 encoding, and the reporting stay in ONE place, shared by every
+ * host.
+ *
+ * NOTHING HERE EVER FAILS AN EXPORT. An image that is too large, of an
+ * unknown type, missing, or unreadable keeps the source the author wrote
+ * and is recorded in the returned report. The host turns that report into
+ * diagnostics lines: per AGENTS.md, a skipped image is a quiet fact on the
+ * diagnostics surface, never a notice and never a failed export.
+ */
+/**
+ * The per-image ceiling for embedding, 2 MiB. An image above it keeps its
+ * original path rather than inflating the exported file by a third of its
+ * own size in base64. Exported so a host with a cheap size check can skip
+ * reading such a file at all and report `oversize` straight away.
+ */
+export declare const MAX_EMBEDDED_IMAGE_BYTES: number;
+/** Every extension `mimeTypeForImageSrc` recognizes, lowercase and without the dot. Exported for a host that wants to name them in its own documentation or tests. */
+export declare const EMBEDDABLE_IMAGE_EXTENSIONS: readonly string[];
+/**
+ * The MIME type for one image source, read from its extension, or
+ * `undefined` when the extension is missing or unrecognized. Any `?query`
+ * or `#fragment` is ignored first, so `logo.png?v=2` still reads as a PNG.
+ */
+export declare function mimeTypeForImageSrc(src: string): string | undefined;
+/**
+ * True for a source this will try to embed: a non-empty, local, relative
+ * path. A scheme of any kind, a protocol-relative `//host/...`, and an
+ * empty or fragment-only value are all left exactly as authored.
+ */
+export declare function isEmbeddableImageSrc(src: string): boolean;
+/** What a host's image reader came back with for one source. */
+export type ExportImageResult = {
+    /** The file's bytes, ready to embed. */
+    readonly kind: 'bytes';
+    readonly bytes: Uint8Array;
+} | {
+    /** The host measured the file and it is over `MAX_EMBEDDED_IMAGE_BYTES`, so it never read it. */
+    readonly kind: 'oversize';
+    readonly byteLength: number;
+} | {
+    /** The source did not resolve to a readable file, or reading it failed. */
+    readonly kind: 'unreadable';
+    /** The verbatim reason, for the diagnostics surface only. */
+    readonly detail?: string;
+};
+/**
+ * Reads one image source for an export. A host resolves the source the way
+ * its own preview resolves one, applies its own jail, and reads the bytes.
+ * It is expected not to throw; one that does is caught by
+ * `embedImagesInHtml` and treated as `unreadable`, so an export is never
+ * lost to a bad path.
+ */
+export type ExportImageReader = (src: string) => ExportImageResult | Promise<ExportImageResult>;
+/** Why one image kept its original source instead of being embedded. Only outcomes worth a diagnostics line appear here; a remote URL is not a skip, it is the documented behavior. */
+export type ImageSkipReason = 'unsupported-type' | 'too-large' | 'unreadable';
+/** One image that was not embedded, and why. */
+export interface SkippedImage {
+    /** The source exactly as it appears in the note. */
+    readonly src: string;
+    readonly reason: ImageSkipReason;
+    /** The file's size, for a `too-large` skip. */
+    readonly byteLength?: number;
+    /** The verbatim reason, for an `unreadable` skip. Diagnostics only. */
+    readonly detail?: string;
+}
+/** What one pass of image embedding did, for the host's diagnostics surface. */
+export interface EmbeddedImageReport {
+    /** The sources that became `data:` URIs, in document order. */
+    readonly embedded: readonly string[];
+    /** How many bytes of image data the file gained, before base64 expansion. */
+    readonly embeddedBytes: number;
+    /** Every local image that kept its original source, and why. */
+    readonly skipped: readonly SkippedImage[];
+    /** How many sources were left alone because they are remote or already embedded. Never a skip; counted only so a host can say the file still reaches the network. */
+    readonly remote: number;
+}
+/** An empty report, for an export that embedded nothing because no host reader was offered. */
+export declare const EMPTY_IMAGE_REPORT: EmbeddedImageReport;
+/**
+ * Base64 for a byte array, hand-rolled so this module needs neither
+ * `Buffer` (Node only) nor `btoa` (which cannot take bytes without a
+ * lossy string round trip) and stays environment-free, matching how this
+ * repo hand-rolls its manifest validation and `uses:` reader rather than
+ * taking a dependency for something this small.
+ */
+export declare function encodeBase64(bytes: Uint8Array): string;
+/** One image's bytes as a `data:` URI. Base64 output is alphanumeric plus `+/=`, so it is always safe inside a double-quoted HTML attribute with no further escaping. */
+export declare function toImageDataUri(bytes: Uint8Array, mimeType: string): string;
+/**
+ * Rewrites every embeddable local `<img src>` in `html` into a `data:` URI,
+ * using `readImage` to fetch each source's bytes, and reports what happened
+ * to every image it saw.
+ *
+ * Each distinct source is read at most once, so a note that shows the same
+ * picture five times reads and encodes it once and embeds the same URI five
+ * times. Never throws: a reader that throws is recorded as `unreadable` and
+ * that one image keeps its original source.
+ */
+export declare function embedImagesInHtml(html: string, readImage: ExportImageReader): Promise<{
+    html: string;
+    report: EmbeddedImageReport;
+}>;