/**
 * Syntactic scanner for v2 .sdoc files.
 *
 * A .sdoc file is: optional <script> at the top, entity blocks in the
 * middle ([SHOWCASE] / [DOC] / [PAGE] / [LAYOUT], with lowercase sub-blocks
 * [preview] / [example] inside [SHOWCASE] and [example] inside [DOC]),
 * optional <style> at the bottom.
 *
 * The scanner is line-anchored and non-balancing: tags are recognized only
 * at the start of a line and only where the current state allows them, so
 * block bodies may contain any text — including square brackets — without
 * escaping. Inside a body, only the matching closer line terminates it.
 *
 * This layer is purely syntactic: it reports structure, attribute values
 * and precise spans, and recovers from errors so an editor can keep
 * getting diagnostics for the rest of the file. Semantic validation
 * (required attributes, uniqueness, literal-only args) lives in parser.ts.
 */
export interface Span {
    start: number;
    end: number;
}
export type EntityKind = 'SHOWCASE' | 'PATTERNS' | 'DOC' | 'PAGE' | 'LAYOUT';
export type SubBlockKind = 'preview' | 'example' | 'prose' | 'notes' | 'todo' | 'glossary';
export declare const ENTITY_KINDS: readonly EntityKind[];
export declare const SUB_BLOCK_KINDS: readonly SubBlockKind[];
/** Blocks whose body is prose or a list rather than a Svelte fragment: they
 * are never staged, never compiled, and carry no block script or style. */
export declare const TEXT_BLOCK_KINDS: readonly SubBlockKind[];
/** Tag names that open sub-blocks, in their canonical (uppercase) spelling.
 * `[COMPONENT]` documents a component (its internal kind is 'preview');
 * `[EXAMPLE]` is a frozen snippet. */
export declare const SUB_BLOCK_TAGS: readonly string[];
/**
 * The text block a whole line opens, or null.
 *
 * Stricter than the other tags in two ways, and both are the same reason: a
 * markdown link is `[notes](…)`, which is prose that would otherwise scan as a
 * block opener. These blocks carry **no attributes**, so a line with anything
 * after the tag is not one of them; and they are **uppercase only**, having
 * never existed in lowercase, so `[notes](…)` in prose stays prose.
 */
export declare function textBlockKindOf(trimmedLine: string): SubBlockKind | null;
/** The closer for a text block of `kind`. */
export declare function textBlockCloser(kind: SubBlockKind): string;
/**
 * The kind a sub-block tag opens, or null for an unknown tag.
 *
 * **Case-insensitive on purpose.** Sub-blocks were lowercase until 0.0.139 and
 * uppercase after it, and old files are never rewritten by a release — the
 * formatter capitalizes them when a document is next formatted, and until then
 * both spellings mean the same block. Since formatting is opt-in, a file
 * nobody formats stays lowercase forever, so this is permanent rather than a
 * deprecation window.
 */
export declare function subBlockKindOf(name: string): SubBlockKind | null;
export interface AttrValue {
    /** 'string' for name="text", 'expression' for name={expr}, 'bare' for a lone name */
    kind: 'string' | 'expression' | 'bare';
    /** Exact source between the quotes/braces ('' for bare attributes) */
    raw: string;
    /** Span of the whole attribute (name through closing quote/brace) */
    span: Span;
    /** Span of `raw` inside the source */
    valueSpan: Span;
}
export type Attrs = Record<string, AttrValue>;
export interface SubBlock {
    kind: SubBlockKind;
    /** Which `[COMPONENTS]` container this block was written in — 0 for the
     * first in the entity, 1 for the next. Null when it was written directly
     * in the entity body, which a lone `[COMPONENT]` may be. */
    group?: number | null;
    /** The tag as written — 'component', 'preview' (alias), or 'example' —
     * so diagnostics can name the block the author actually typed. */
    tag: string;
    attrs: Attrs;
    /** Raw body between the opener line and the closer line (script/style included) */
    body: string;
    bodySpan: Span;
    /** Optional block-level <script> — must be the first content of the body */
    script: TagBlock | null;
    /** Optional block-level <style> — must be the last content of the body */
    style: TagBlock | null;
    /** Raw markup between the block script and block style (the whole body
     * when the block declares neither) */
    markup: string;
    markupSpan: Span;
    openerSpan: Span;
    span: Span;
}
export interface Entity {
    kind: EntityKind;
    attrs: Attrs;
    /** SHOWCASE: preview/example sub-blocks. DOC: example sub-blocks.
     * PAGE/LAYOUT: always empty. */
    blocks: SubBlock[];
    /** Entity-level <script> — the first content of the entity body */
    script: TagBlock | null;
    /** Entity-level <style> — the last content of the entity body */
    style: TagBlock | null;
    /** DOC/PAGE/LAYOUT: the raw body (for DOC it includes any [example] blocks,
     * addressable via their spans). SHOWCASE: '' (body text between blocks is an error). */
    body: string;
    bodySpan: Span;
    openerSpan: Span;
    span: Span;
}
/** A top-level <script> or <style> tag block. */
export interface TagBlock {
    /** Raw text between the tag name and '>', e.g. ' lang="ts"' */
    attrsText: string;
    content: string;
    contentSpan: Span;
    span: Span;
}
export interface ScanError {
    code: string;
    message: string;
    span: Span;
}
export interface SdocFile {
    script: TagBlock | null;
    style: TagBlock | null;
    entities: Entity[];
    errors: ScanError[];
    source: string;
}
export declare function scanSdoc(source: string): SdocFile;
/** Convert an offset to a 0-based line/column pair (for editors/CLI output). */
export declare function offsetToPosition(source: string, offset: number): {
    line: number;
    column: number;
};