@almadar/core 10.101.0 → 10.103.0

package/dist/lolo-document/index.d.ts

@@ -0,0 +1,166 @@
+/**
+ * lolo-document — structural index + text-span mutations over a `.lolo` source
+ * (moved from Kura's scene editor so every editor of `.lolo` shares one owner).
+ *
+ * NOT a lolo parser: `orbital-lolo` (the `orb` binary) is the parser of record and the
+ * server's emit + validate is the correctness gate after every mutation. This module only
+ * locates the constructs the editor mutates (uses / entity / traits / config entries /
+ * events / listens / pages) as byte spans and produces `TextEdit[]`; every byte outside a
+ * touched span is preserved verbatim, so `applyEdits(text, [])` is the identity.
+ */
+interface Span {
+    start: number;
+    end: number;
+}
+interface TextEdit {
+    start: number;
+    end: number;
+    insert: string;
+}
+type LoloValue = string | number | boolean | null | ReadonlyArray<LoloValue> | {
+    readonly [key: string]: LoloValue;
+};
+interface UsesDecl {
+    alias: string;
+    from: string;
+    span: Span;
+}
+interface TypeDecl {
+    name: string;
+    span: Span;
+}
+interface EntityFieldDecl {
+    name: string;
+    type: string;
+    span: Span;
+}
+interface EntityDecl {
+    name: string;
+    tags: string;
+    fields: EntityFieldDecl[];
+    span: Span;
+    bodySpan: Span;
+}
+interface ConfigEntry {
+    key: string;
+    /** Present for inline (typed) config declarations: `key : Type = value`. */
+    type?: string;
+    valueSpan: Span;
+    rawValue: string;
+    span: Span;
+}
+interface EventsEntry {
+    upstream: string;
+    local: string;
+    span: Span;
+}
+interface BlockDecl {
+    span: Span;
+    bodySpan: Span;
+}
+interface ConfigBlock extends BlockDecl {
+    entries: ConfigEntry[];
+}
+interface EventsBlock extends BlockDecl {
+    entries: EventsEntry[];
+}
+interface TraitDecl {
+    name: string;
+    inline: boolean;
+    alias?: string;
+    trait?: string;
+    entity?: string;
+    rebindable: boolean;
+    span: Span;
+    bodySpan: Span;
+    config?: ConfigBlock;
+    events?: EventsBlock;
+    listens?: BlockDecl;
+    stateBlocks: Array<{
+        name: string;
+        span: Span;
+    }>;
+}
+interface PageDecl {
+    path: string;
+    name?: string;
+    traits: string[];
+    /** The ` ->` token (leading whitespace included); absent for a trait-less page. */
+    arrowSpan?: Span;
+    /** The trait list after `->`; for a trait-less page, the empty insertion point after the head. */
+    traitsSpan: Span;
+    span: Span;
+}
+interface LoloDocument {
+    text: string;
+    app?: {
+        name: string;
+        version: string;
+        span: Span;
+    };
+    orbital: {
+        name: string;
+        span: Span;
+        bodySpan: Span;
+    };
+    uses: UsesDecl[];
+    types: TypeDecl[];
+    entities: EntityDecl[];
+    traits: TraitDecl[];
+    pages: PageDecl[];
+    /** Indentation (whitespace string) of the orbital's direct children. */
+    indent: string;
+}
+interface ListenRoute {
+    source: string;
+    event: string;
+    local: string;
+}
+/**
+ * Find the index of the matching closing delimiter for the opener at `openIdx`.
+ * Respects strings and comments. Returns -1 when unbalanced.
+ */
+declare function matchDelimiter(text: string, openIdx: number): number;
+declare function lineStart(text: string, idx: number): number;
+/** The `uses` alias for a behavior: its kebab name in PascalCase, the identifier form `USES_RE` indexes (`std-arcade-flow` → `StdArcadeFlow`). */
+declare function aliasForBehavior(behavior: string): string;
+declare function parseLoloDocument(text: string): LoloDocument;
+declare function applyEdits(text: string, edits: ReadonlyArray<TextEdit>): string;
+/**
+ * Render a value in the `.lolo` literal style the corpus uses: objects inline with commas,
+ * arrays of objects one element per line (no commas), scalar arrays inline space-separated.
+ */
+declare function formatLoloValue(value: LoloValue, indent?: string): string;
+declare function addUses(doc: LoloDocument, alias: string, from: string): TextEdit[];
+declare function usesAlias(doc: LoloDocument, from: string): string | undefined;
+interface AddTraitRefInput {
+    name: string;
+    alias: string;
+    trait: string;
+    entity: string;
+    config: Record<string, LoloValue>;
+    events?: Record<string, string>;
+}
+declare function addTraitRef(doc: LoloDocument, input: AddTraitRefInput): TextEdit[];
+declare function removeTrait(doc: LoloDocument, name: string): TextEdit[];
+declare function findPage(doc: LoloDocument, path: string): PageDecl;
+declare function appendPageTrait(doc: LoloDocument, path: string, traitName: string): TextEdit[];
+declare function removePageTrait(doc: LoloDocument, path: string, traitName: string): TextEdit[];
+declare function setConfigValue(doc: LoloDocument, traitName: string, key: string, value: LoloValue): TextEdit[];
+/** Top-level elements of an array literal `[ … ]` as spans (balanced, string-aware). */
+declare function arrayElementSpans(text: string, arraySpan: Span): Span[];
+declare function setConfigArrayRow(doc: LoloDocument, traitName: string, key: string, index: number, patch: Record<string, LoloValue>): TextEdit[];
+declare function renameEvent(doc: LoloDocument, traitName: string, upstream: string, local: string): TextEdit[];
+/**
+ * Add a listens route. On a referenced trait a `listens {}` override REPLACES the atom's
+ * set, so the atom's own routes are restated first (`atomRoutes`) — the rebind-listens trap.
+ */
+declare function addListens(doc: LoloDocument, traitName: string, route: ListenRoute, atomRoutes?: ReadonlyArray<ListenRoute>): TextEdit[];
+interface LoloFieldInput {
+    name: string;
+    type: string;
+    default?: LoloValue;
+}
+declare function addEntityFields(doc: LoloDocument, entityName: string, fields: ReadonlyArray<LoloFieldInput>): TextEdit[];
+
+export { type AddTraitRefInput, type BlockDecl, type ConfigBlock, type ConfigEntry, type EntityDecl, type EntityFieldDecl, type EventsBlock, type EventsEntry, type ListenRoute, type LoloDocument, type LoloFieldInput, type LoloValue, type PageDecl, type Span, type TextEdit, type TraitDecl, type TypeDecl, type UsesDecl, addEntityFields, addListens, addTraitRef, addUses, aliasForBehavior, appendPageTrait, applyEdits, arrayElementSpans, findPage, formatLoloValue, lineStart, matchDelimiter, parseLoloDocument, removePageTrait, removeTrait, renameEvent, setConfigArrayRow, setConfigValue, usesAlias };