@pixerate/editor 0.19.0 → 0.20.0

package/dist/grammar/index.d.ts

@@ -1,45 +1,64 @@
-import { T as Token, b as Template, c as TemplateVersion } from '../tokens-7kRTEtPb.js';
-export { C as ColorGradient, I as INSTRUCTION_REGEX, a as TEMPLATE_REGEX, d as TokenType, V as VARIABLE_REGEX, i as instructionRegex, t as templateRegex, v as variableRegex } from '../tokens-7kRTEtPb.js';
+import { T as Token, P as PromptDiagnostic, d as PromptValues, f as Template, g as TemplateVersion, a as ConditionalKind, c as PromptValue } from '../tokens-CyLZmIei.js';
+export { C as ColorGradient, I as INSTRUCTION_REGEX, b as PromptDiagnosticCode, e as TEMPLATE_REGEX, h as TokenType, V as VARIABLE_REGEX, i as instructionRegex, t as templateRegex, v as variableRegex } from '../tokens-CyLZmIei.js';
 
+interface TokenizeResult {
+    tokens: Token[];
+    /** Unbalanced conditional tags, which were emitted as text. */
+    diagnostics: PromptDiagnostic[];
+}
 /**
  * Parses any prompt string into an array of typed tokens in linear order.
  * Plain text between tokens is preserved as `{ type: 'text' }`.
+ *
+ * Conditional section tags (`{?name}`, `{!name}`, `{/name}`) are only emitted
+ * as `conditional` tokens when balanced; unbalanced tags become text. Use
+ * `tokenizePromptWithDiagnostics` to find out which tags were rejected.
  */
 declare function tokenizePrompt(text: string): Token[];
-
 /**
- * Finds the latest version of a template based on `latestVersion` or last version entry.
+ * Returns the diagnostics `tokenizePrompt` would report for `text`.
  */
-declare function getLatestVersion(template: Template): TemplateVersion | undefined;
+declare function getPromptDiagnostics(text: string): PromptDiagnostic[];
+/**
+ * Like `tokenizePrompt`, but also reports unbalanced conditional tags.
+ */
+declare function tokenizePromptWithDiagnostics(text: string): TokenizeResult;
+
 interface ResolveTemplatesOptions {
     bindings?: Record<string, string>;
     maxDepth?: number;
+    /**
+     * Values for `{variable}` slots and `{?variable}` sections. When omitted,
+     * variables, defaults and section tags are left exactly as written.
+     */
+    values?: PromptValues;
 }
-/** Marker substituted for a template tag that would recurse into itself. */
-declare const TEMPLATE_LOOP_ERROR = "[Template loop detected]";
-/** Marker substituted for a template tag nested deeper than `maxDepth`. */
-declare const TEMPLATE_DEPTH_ERROR = "[Template max depth exceeded]";
-/**
- * Returns the body a template tag resolves to, honoring version bindings.
- */
-declare function getTemplateBody(template: Template, bindings?: Record<string, string>): string | undefined;
 /**
  * Recursively resolves template tags `{{template_name}}` in a given text.
  * A tag that would recurse into itself is replaced with `TEMPLATE_LOOP_ERROR`,
  * and a tag nested deeper than `maxDepth` with `TEMPLATE_DEPTH_ERROR`; the rest
  * of the text still resolves normally.
+ *
+ * Pass `options.values` to also fill variables (falling back to their
+ * `{name|default}`) and evaluate `{?name}…{/name}` / `{!name}…{/name}`
+ * sections, including those inside template bodies. See `resolvePrompt` for
+ * the source map and diagnostics.
  */
 declare function resolveTemplates(text: string, templates?: Template[], options?: ResolveTemplatesOptions): string;
 /**
- * Replaces `{variableName}` with values from a dictionary.
+ * Replaces `{variableName}` with values from a dictionary, falling back to a
+ * `{variableName|default}` when no value is supplied, and evaluates
+ * `{?name}…{/name}` / `{!name}…{/name}` sections. Variables with neither a
+ * value nor a default are left as written. Templates are not expanded.
  */
-declare function resolveVariables(text: string, values: Record<string, string | number>): string;
+declare function resolveVariables(text: string, values: PromptValues): string;
 /**
  * Extracts unique template names referenced in text.
  */
 declare function extractTemplateNames(text: string): string[];
 /**
- * Extracts unique variable names referenced in text.
+ * Extracts unique variable names referenced in text, including names used by
+ * conditional section tags. Defaults and descriptions are stripped.
  */
 declare function extractVariableNames(text: string): string[];
 /**
@@ -47,21 +66,41 @@ declare function extractVariableNames(text: string): string[];
  */
 declare function extractInstructionNames(text: string): string[];
 
+/**
+ * One contiguous piece of resolved output and the raw range it came from.
+ *
+ * - `raw`: copied verbatim; offsets map character by character.
+ * - `template`: the expansion of a `{{template}}` tag.
+ * - `variable`: a substituted value or `|default` for a `{variable}` tag.
+ * - `conditional`: a section tag, or a whole removed section. These segments
+ *   are empty in the resolved text (`resolvedStart === resolvedEnd`).
+ *
+ * Offsets inside non-raw segments map to the start of their raw range.
+ */
 interface SourceMapSegment {
     resolvedStart: number;
     resolvedEnd: number;
-    source: "raw" | "template";
+    source: "raw" | "template" | "variable" | "conditional";
     rawStart: number;
     rawEnd: number;
     templateName?: string;
+    /** Variable substituted (`variable`) or tested (`conditional`). */
+    variableName?: string;
+    /** For `variable` segments: whether a supplied value or the default was used. */
+    valueSource?: "value" | "default";
 }
 /**
  * Resolves templates in text while tracking character offset mapping
  * between the raw input and the fully resolved output.
+ *
+ * Pass `options.values` to also substitute variables and evaluate conditional
+ * sections (see `resolvePrompt`); without it the output is unchanged from the
+ * template-only behavior.
  */
-declare function resolveTemplatesWithMapping(text: string, templates?: Template[], templateBindings?: Record<string, string>, options?: Pick<ResolveTemplatesOptions, "maxDepth">): {
+declare function resolveTemplatesWithMapping(text: string, templates?: Template[], templateBindings?: Record<string, string>, options?: Pick<ResolveTemplatesOptions, "maxDepth" | "values">): {
     text: string;
     map: SourceMapSegment[];
+    diagnostics: PromptDiagnostic[];
 };
 /**
  * Maps an offset in resolved text back to the corresponding offset in raw text.
@@ -72,4 +111,185 @@ declare function mapResolvedOffsetToRaw(resolvedOffset: number, map: SourceMapSe
  */
 declare function mapRawOffsetToResolved(rawOffset: number, map: SourceMapSegment[]): number;
 
-export { type ResolveTemplatesOptions, type SourceMapSegment, TEMPLATE_DEPTH_ERROR, TEMPLATE_LOOP_ERROR, Template, TemplateVersion, Token, extractInstructionNames, extractTemplateNames, extractVariableNames, getLatestVersion, getTemplateBody, mapRawOffsetToResolved, mapResolvedOffsetToRaw, resolveTemplates, resolveTemplatesWithMapping, resolveVariables, tokenizePrompt };
+/**
+ * Finds the latest version of a template based on `latestVersion` or last version entry.
+ */
+declare function getLatestVersion(template: Template): TemplateVersion | undefined;
+/** Marker substituted for a template tag that would recurse into itself. */
+declare const TEMPLATE_LOOP_ERROR = "[Template loop detected]";
+/** Marker substituted for a template tag nested deeper than `maxDepth`. */
+declare const TEMPLATE_DEPTH_ERROR = "[Template max depth exceeded]";
+/**
+ * Returns the body a template tag resolves to, honoring version bindings.
+ */
+declare function getTemplateBody(template: Template, bindings?: Record<string, string>): string | undefined;
+interface ResolvePromptOptions {
+    /** Template version bindings (`{ templateName: versionIdOrVersion }`). */
+    bindings?: Record<string, string>;
+    /** Maximum template nesting depth (default 10). */
+    maxDepth?: number;
+    /**
+     * Values for `{variable}` slots and `{?variable}` / `{!variable}` sections.
+     * When omitted, variables and section tags are left exactly as written.
+     */
+    values?: PromptValues;
+}
+interface ResolvePromptResult {
+    text: string;
+    map: SourceMapSegment[];
+    diagnostics: PromptDiagnostic[];
+}
+/**
+ * Resolves a prompt: expands `{{templates}}` recursively (with loop and depth
+ * protection), and, when `values` are given, substitutes `{variables}` (falling
+ * back to their `|default`) and keeps or removes `{?name}…{/name}` sections.
+ *
+ * Template bodies are parsed on their own, so a section must open and close
+ * within the same body. Templates inside a removed section are never expanded
+ * and cannot trigger loop or depth errors. Unbalanced section tags are kept as
+ * literal text and reported in `diagnostics`.
+ *
+ * Returns the resolved text, a source map from resolved to raw offsets, and
+ * diagnostics. With no `values` the text matches the original template-only
+ * resolver exactly.
+ */
+declare function resolvePrompt(text: string, templates?: Template[], options?: ResolvePromptOptions): ResolvePromptResult;
+/** A token annotated with the value it resolves to. */
+interface EvaluatedToken extends Token {
+    /** Variables only, when values were given: the substituted text. */
+    resolvedValue?: string;
+    /** Variables only: whether `resolvedValue` came from `values` or the default. */
+    valueSource?: "value" | "default";
+}
+/**
+ * Tokenizes a prompt for display. Without `values` this is `tokenizePrompt`.
+ * With `values`, sections whose condition fails are removed (tags included),
+ * the tags of kept sections are dropped, and each variable that has a value or
+ * a default carries it in `resolvedValue`. Templates are not expanded; resolve
+ * them first (without values) if the display should show their bodies.
+ */
+declare function evaluatePromptTokens(text: string, values?: PromptValues): EvaluatedToken[];
+
+/** Result of classifying the text between the braces of a `{…}` token. */
+type ParsedVariableBody = {
+    kind: "variable";
+    name: string;
+    defaultValue?: string;
+    description?: string;
+} | {
+    kind: "conditional";
+    conditional: ConditionalKind;
+    name: string;
+};
+/**
+ * Removes grammar escapes: `\|`, `\{`, `\}` and `\\` become the bare character.
+ * Any other backslash is kept, so Windows paths and regex-like text survive.
+ */
+declare function unescapeVariableText(text: string): string;
+/**
+ * Escapes text so it can be embedded as a variable default or description.
+ */
+declare function escapeVariableText(text: string): string;
+/**
+ * Classifies the inner text of a `{…}` token.
+ *
+ * - `{?name}`, `{!name}`, `{/name}` are conditional section tags. The name may
+ *   not contain `|`; otherwise the token is an ordinary variable.
+ * - `{name|default|description}` is a variable. Each part is trimmed and
+ *   unescaped. A default is present whenever a `|` is (it may be empty), and
+ *   anything after the second unescaped `|` belongs to the description.
+ */
+declare function parseVariableBody(inner: string): ParsedVariableBody;
+/**
+ * Whether a supplied value counts as "set" for a `{?name}` condition:
+ * not `null`/`undefined`/`false`, and not blank once stringified.
+ */
+declare function isPromptValueSet(value: PromptValue): boolean;
+/**
+ * Returns the text a supplied value substitutes, or `undefined` when the
+ * variable should fall back to its default. An explicit empty string is a
+ * value (it renders as nothing); `null`/`undefined` are not.
+ */
+declare function getSuppliedValue(values: PromptValues, name: string): string | undefined;
+/** Whether a section opened by `{?name}` / `{!name}` keeps its body. */
+declare function evaluateCondition(conditional: Exclude<ConditionalKind, "end">, name: string, values: PromptValues): boolean;
+interface ConditionalTagLike {
+    conditional: ConditionalKind;
+    name: string;
+}
+interface ConditionalTagMatch {
+    /** Index of the partner tag, or -1 when the tag is unbalanced. */
+    partner: number;
+    /** Set when unbalanced. */
+    error?: "unclosed-section" | "unexpected-close";
+}
+/**
+ * Pairs conditional tags given in document order. A close tag pairs with the
+ * nearest open tag of the same name; open tags skipped over are reported as
+ * unclosed, and a close tag with no open partner as unexpected. Unbalanced tags
+ * never throw: callers treat them as literal text. The surviving pairs are
+ * always properly nested.
+ */
+declare function matchConditionalTags(tags: ConditionalTagLike[]): ConditionalTagMatch[];
+
+/** Everything a prompt (and, optionally, its templates) says about one variable. */
+interface VariableDescriptor {
+    name: string;
+    /** First `{name|default}` found. */
+    defaultValue?: string;
+    /** First `{name|default|description}` found. */
+    description?: string;
+    /** Appears as a `{name}` slot. */
+    usedAsValue: boolean;
+    /** Appears in a `{?name}` / `{!name}` condition. */
+    usedInCondition: boolean;
+    /** Number of `{name…}` slots and condition tags (closing tags excluded). */
+    occurrences: number;
+    /** Templates whose bodies mention the variable, in discovery order. */
+    templates: string[];
+}
+interface ExtractVariablesOptions {
+    /** Templates to search recursively for further variables. */
+    templates?: Template[];
+    bindings?: Record<string, string>;
+    /** Maximum template nesting depth to search (default 10). */
+    maxDepth?: number;
+}
+/**
+ * Lists every variable a prompt uses, in order of first appearance, with its
+ * default and description. Templates referenced by the prompt are searched
+ * recursively when `options.templates` is given (loops are skipped). All
+ * sections are searched, whatever their condition would evaluate to.
+ */
+declare function extractVariables(text: string, options?: ExtractVariablesOptions): VariableDescriptor[];
+/** A headless description of one input in a variable fill-in form. */
+interface VariableFormField {
+    name: string;
+    /** The variable's description, or its name. */
+    label: string;
+    /** The variable's default, or an empty string. */
+    placeholder: string;
+    defaultValue?: string;
+    description?: string;
+    /**
+     * The variable is used as a slot and has no default, so leaving it blank
+     * leaves the `{name}` placeholder in the resolved prompt.
+     */
+    required: boolean;
+    /** Only used by `{?name}` / `{!name}` conditions, never substituted. */
+    conditionOnly: boolean;
+}
+/**
+ * Builds field descriptors for a fill-in form (Word's FILLIN analogue): one
+ * per variable, labelled with its description and using its default as the
+ * placeholder. Feed the entered text through `compactVariableValues` before
+ * resolving so blank inputs fall back to defaults.
+ */
+declare function getVariableFormFields(text: string, options?: ExtractVariablesOptions): VariableFormField[];
+/**
+ * Drops blank entries from form input so the resolver falls back to each
+ * variable's default (an explicit `""` value would otherwise render as empty).
+ */
+declare function compactVariableValues(input: Record<string, string | null | undefined>): PromptValues;
+
+export { ConditionalKind, type ConditionalTagLike, type ConditionalTagMatch, type EvaluatedToken, type ExtractVariablesOptions, type ParsedVariableBody, PromptDiagnostic, PromptValue, PromptValues, type ResolvePromptOptions, type ResolvePromptResult, type ResolveTemplatesOptions, type SourceMapSegment, TEMPLATE_DEPTH_ERROR, TEMPLATE_LOOP_ERROR, Template, TemplateVersion, Token, type TokenizeResult, type VariableDescriptor, type VariableFormField, compactVariableValues, escapeVariableText, evaluateCondition, evaluatePromptTokens, extractInstructionNames, extractTemplateNames, extractVariableNames, extractVariables, getLatestVersion, getPromptDiagnostics, getSuppliedValue, getTemplateBody, getVariableFormFields, isPromptValueSet, mapRawOffsetToResolved, mapResolvedOffsetToRaw, matchConditionalTags, parseVariableBody, resolvePrompt, resolveTemplates, resolveTemplatesWithMapping, resolveVariables, tokenizePrompt, tokenizePromptWithDiagnostics, unescapeVariableText };

package/dist/grammar/index.js

@@ -1,45 +1,73 @@
 import {
   TEMPLATE_DEPTH_ERROR,
   TEMPLATE_LOOP_ERROR,
+  compactVariableValues,
+  evaluatePromptTokens,
   extractInstructionNames,
   extractTemplateNames,
   extractVariableNames,
+  extractVariables,
   getLatestVersion,
+  getPromptDiagnostics,
   getTemplateBody,
+  getVariableFormFields,
   mapRawOffsetToResolved,
   mapResolvedOffsetToRaw,
+  resolvePrompt,
   resolveTemplates,
   resolveTemplatesWithMapping,
   resolveVariables,
-  tokenizePrompt
-} from "../chunk-O7LOPQMH.js";
+  tokenizePrompt,
+  tokenizePromptWithDiagnostics
+} from "../chunk-OYXSKQFR.js";
 import {
   INSTRUCTION_REGEX,
   TEMPLATE_REGEX,
   VARIABLE_REGEX,
+  escapeVariableText,
+  evaluateCondition,
+  getSuppliedValue,
   instructionRegex,
+  isPromptValueSet,
+  matchConditionalTags,
+  parseVariableBody,
   templateRegex,
+  unescapeVariableText,
   variableRegex
-} from "../chunk-GLSIZKOX.js";
+} from "../chunk-B2ZRLN4S.js";
 export {
   INSTRUCTION_REGEX,
   TEMPLATE_DEPTH_ERROR,
   TEMPLATE_LOOP_ERROR,
   TEMPLATE_REGEX,
   VARIABLE_REGEX,
+  compactVariableValues,
+  escapeVariableText,
+  evaluateCondition,
+  evaluatePromptTokens,
   extractInstructionNames,
   extractTemplateNames,
   extractVariableNames,
+  extractVariables,
   getLatestVersion,
+  getPromptDiagnostics,
+  getSuppliedValue,
   getTemplateBody,
+  getVariableFormFields,
   instructionRegex,
+  isPromptValueSet,
   mapRawOffsetToResolved,
   mapResolvedOffsetToRaw,
+  matchConditionalTags,
+  parseVariableBody,
+  resolvePrompt,
   resolveTemplates,
   resolveTemplatesWithMapping,
   resolveVariables,
   templateRegex,
   tokenizePrompt,
+  tokenizePromptWithDiagnostics,
+  unescapeVariableText,
   variableRegex
 };
 //# sourceMappingURL=index.js.map

package/dist/history/index.d.cts

@@ -1,43 +1,4 @@
-interface Command {
-    execute: () => void;
-    undo: () => void;
-    redo?: () => void;
-    name: string;
-    tag?: string;
-    timestamp?: number;
-}
-interface HistoryState {
-    canUndo: boolean;
-    canRedo: boolean;
-    undoName: string;
-    redoName: string;
-    undoCount: number;
-    redoCount: number;
-}
-interface HistoryManagerOptions {
-    /**
-     * Maximum number of undo states to keep. Defaults to 50.
-     */
-    maxDepth?: number;
-    /**
-     * Optional callback fired whenever the history state changes.
-     */
-    onStateChange?: (state: HistoryState) => void;
-}
-interface SnapshotCommandOptions<T> {
-    name: string;
-    before: T;
-    after: T;
-    apply: (state: T) => void;
-    tag?: string;
-}
-interface MergedExecutionOptions {
-    /**
-     * Window in milliseconds during which commands with the same tag will be coalesced.
-     * Defaults to 300ms.
-     */
-    windowMs?: number;
-}
+import { H as HistoryManagerOptions, a as HistoryState, C as Command, M as MergedExecutionOptions, S as SnapshotCommandOptions } from '../types-BZgcDsC5.cjs';
 
 /**
  * UI-agnostic History and Undo/Redo manager supporting command closures,
@@ -111,4 +72,4 @@ declare class HistoryManager {
  */
 declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
 
-export { type Command, HistoryManager, type HistoryManagerOptions, type HistoryState, type MergedExecutionOptions, type SnapshotCommandOptions, createHistoryManager };
+export { Command, HistoryManager, HistoryManagerOptions, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, createHistoryManager };

package/dist/history/index.d.ts

@@ -1,43 +1,4 @@
-interface Command {
-    execute: () => void;
-    undo: () => void;
-    redo?: () => void;
-    name: string;
-    tag?: string;
-    timestamp?: number;
-}
-interface HistoryState {
-    canUndo: boolean;
-    canRedo: boolean;
-    undoName: string;
-    redoName: string;
-    undoCount: number;
-    redoCount: number;
-}
-interface HistoryManagerOptions {
-    /**
-     * Maximum number of undo states to keep. Defaults to 50.
-     */
-    maxDepth?: number;
-    /**
-     * Optional callback fired whenever the history state changes.
-     */
-    onStateChange?: (state: HistoryState) => void;
-}
-interface SnapshotCommandOptions<T> {
-    name: string;
-    before: T;
-    after: T;
-    apply: (state: T) => void;
-    tag?: string;
-}
-interface MergedExecutionOptions {
-    /**
-     * Window in milliseconds during which commands with the same tag will be coalesced.
-     * Defaults to 300ms.
-     */
-    windowMs?: number;
-}
+import { H as HistoryManagerOptions, a as HistoryState, C as Command, M as MergedExecutionOptions, S as SnapshotCommandOptions } from '../types-BZgcDsC5.js';
 
 /**
  * UI-agnostic History and Undo/Redo manager supporting command closures,
@@ -111,4 +72,4 @@ declare class HistoryManager {
  */
 declare function createHistoryManager(options?: HistoryManagerOptions): HistoryManager;
 
-export { type Command, HistoryManager, type HistoryManagerOptions, type HistoryState, type MergedExecutionOptions, type SnapshotCommandOptions, createHistoryManager };
+export { Command, HistoryManager, HistoryManagerOptions, HistoryState, MergedExecutionOptions, SnapshotCommandOptions, createHistoryManager };