import { type OutputLayout } from "./import-path.js";
/** The minimal shape needed to place a docs page / compute a link to it: a
 *  short name and its EFFECTIVE package. Build one from a metadata node via
 *  `docPageNode()`. */
export interface DocPageNode {
    readonly name: string;
    readonly package?: string | undefined;
}
/** A metadata node enough to derive page placement. `resolutionKey()` carries
 *  the EFFECTIVE package (own package OR the file-default captured at parse
 *  time) folded as `<pkg>::<name>` — `.package` alone is often undefined for
 *  objects (FR5d keeps object fqn() bare), so we read placement off the
 *  resolution key instead. */
interface PlaceableNode {
    readonly name: string;
    resolutionKey(): string;
}
/** Effective package of a placeable node: the prefix of `resolutionKey()`
 *  before the trailing `::<name>`, or undefined when the node is package-less. */
export declare function effectivePackage(node: PlaceableNode): string | undefined;
/** Build a placement node ({name, effective package}) from a metadata node. The
 *  single bridge from a loaded node to the path/href helpers — so file location
 *  and link href derive from the SAME effective package. */
export declare function docPageNode(node: PlaceableNode): DocPageNode;
/** Output path (relative to the docs out dir) for a node's `.md` page.
 *  Flat → `<name>.md` (today's value, byte-identical). Package → folded under
 *  the package path (`acme/sales/Order.md`); a package-less node stays at root. */
export declare function docPageOutputPath(layout: OutputLayout, node: DocPageNode): string;
/** Relative href FROM `fromNode`'s page TO `toNode`'s page. Derived from the
 *  same `docPageOutputPath()` placement, so a link always points at the file's
 *  real location in BOTH layouts. Flat → `./<to>.md`; package → a correct
 *  relative path (e.g. `../comms/OrderEmail.md`). */
export declare function docPageHref(layout: OutputLayout, fromNode: DocPageNode, toNode: DocPageNode): string;
/** Relative href between two doc pages whose output paths (relative to the shared
 *  docs outDir) may sit under different surface sub-roots — e.g. model `Order.md`
 *  and api `api/Order.md`. The shared relative-path rule, over raw paths;
 *  docPageHref delegates its package-layout branch here. */
export declare function surfaceCrossHref(fromOutputPath: string, toOutputPath: string): string;
/** Href FROM a page (at `fromOutputPath`, relative to the docs root) TO a page
 *  (`page`, relative to the surface's own root) in an api surface. Relative via
 *  `surfaceCrossHref` when the surface is in the same tree; absolute `baseUrl/page`
 *  when the surface declares a baseUrl (federated / separate repo). */
export declare function apiSurfaceHref(fromOutputPath: string, surface: {
    subDir: string;
    baseUrl?: string;
}, page: string): string;
/** A page about to be emitted, paired with the FQN of the node that produced it
 *  (for a precise collision diagnostic). */
export interface DocPagePlacement {
    path: string;
    fqn: string;
}
/** Hard backstop against silent overwrite (ALL layouts): if two placements
 *  resolve to the SAME output path, THROW naming both colliding node FQNs and
 *  the path. Guarantees a docs run never silently drops a page. */
export declare function assertNoDuplicateDocPaths(placements: DocPagePlacement[]): void;
export {};
//# sourceMappingURL=docs-paths.d.ts.map