spytial-core 4.0.0 → 4.0.1

package/dist/types/components/CndLayoutInterface.d.ts

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { Diagnostic, DomainSchema, SelectorAssistant, SpecEditorThemeInput } from '../spec-editor';
+import type { Diagnostic, DomainSchema, LayoutAssistant, SelectorAssistant, SpecEditorThemeInput } from '../spec-editor';
 import type { ConstraintData, DirectiveData } from './NoCodeView/interfaces';
 import type { IInputDataInstance } from '../data-instance/interfaces';
 /**
@@ -45,6 +45,12 @@ export interface CndLayoutInterfaceProps {
     theme?: SpecEditorThemeInput;
     /** Selector-writing assistant hook. */
     selectorAssistant?: SelectorAssistant;
+    /**
+     * Whole-spec suggestion hook. Supplying `suggest` adds a Suggest button to
+     * the editor toolbar; the proposal is applied to the document (one undo step)
+     * and surfaced through `onChange` like any other edit.
+     */
+    layoutAssistant?: LayoutAssistant;
     /** Row density. */
     density?: 'compact' | 'comfortable';
     /** Syntax highlighting in code view + selector fields (default true). */

package/dist/types/components/index.d.ts

@@ -26,6 +26,7 @@ export { ProjectionControls, ProjectionOrchestrator } from './ProjectionControls
 export type { ProjectionControlsProps, ProjectionChoice, ProjectionOrchestratorProps, ProjectionOrchestratorResult, } from './ProjectionControls';
 export { CndLayoutInterface } from './CndLayoutInterface';
 export type { CndLayoutInterfaceProps } from './CndLayoutInterface';
+export type { SelectorAssistant, SelectorAssistContext, Completion, LayoutAssistant, LayoutAssistContext, LayoutSuggestionResult, LayoutSuggestionDetail, LayoutSuggestionConfidence, LayoutSuggestionOutcome, } from '../spec-editor';
 export { generateLayoutSpecYaml, parseLayoutSpecToData } from './NoCodeView';
 export type { ConstraintData, DirectiveData } from './NoCodeView';
 export { EvaluatorRepl } from './EvaluatorRepl/EvaluatorRepl';

package/dist/types/spec-editor/domain/layout-assistant.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Whole-spec suggestion hook (HOOK 3).
+ *
+ * Where {@link SelectorAssistant} assists one selector field, a
+ * `LayoutAssistant` proposes an entire layout. Integrators provide the policy
+ * — a heuristic analyzer, a model, a synthesis engine — and the editor owns the
+ * affordance: a toolbar button, the apply-through-document semantics (so the
+ * suggestion is one undo step and refreshes the builder in place), and a
+ * read-only panel explaining what the suggester did.
+ *
+ * The contract is deliberately domain-agnostic. The context is
+ * `{domain, instance, currentYaml}` and nothing else; the optional
+ * per-suggestion metadata (`rationale`, `confidence`, `outcome`) is rendered
+ * generically, and a suggester with no such vocabulary simply omits it. Any
+ * host can plug in any suggester.
+ *
+ * Framework-agnostic — no React.
+ */
+import type { IInputDataInstance } from '../../data-instance/interfaces';
+import type { DomainSchema } from './domain-schema';
+export interface LayoutAssistContext {
+    /** Domain awareness, as resolved by the editor (`domain` prop ?? extracted from `instance`). */
+    domain?: DomainSchema;
+    /** The live data instance, when the host passed one. */
+    instance?: IInputDataInstance;
+    /** The full current spec text, so a suggester can extend rather than replace. */
+    currentYaml: string;
+}
+/** How much the suggester trusts an individual suggestion. */
+export type LayoutSuggestionConfidence = 'high' | 'medium' | 'low';
+/**
+ * What became of a suggestion in the returned YAML. Suggesters that validate
+ * their own output use this to admit a fallback (`weakened`) or a drop
+ * (`omitted`) instead of silently shipping a shorter spec.
+ */
+export type LayoutSuggestionOutcome = 'applied' | 'weakened' | 'omitted';
+/** One line of the suggestions panel. All fields beyond `id` are optional. */
+export interface LayoutSuggestionDetail {
+    /** Stable identifier, unique within a result. Used as the React key. */
+    id: string;
+    /** Why the suggester proposed this. Rendered as the body of the row. */
+    rationale?: string;
+    confidence?: LayoutSuggestionConfidence;
+    outcome?: LayoutSuggestionOutcome;
+}
+export interface LayoutSuggestionResult {
+    /** The proposed spec. Replaces the document wholesale, as one undo step. */
+    yaml: string;
+    /** Per-suggestion detail for the panel. Omit for an opaque suggestion. */
+    suggestions?: readonly LayoutSuggestionDetail[];
+    /** Result-level remarks (e.g. "2 suggestions used a weaker fallback"). */
+    notes?: readonly string[];
+}
+export interface LayoutAssistant {
+    /**
+     * Propose a whole spec for the current data. Powers the toolbar's Suggest
+     * affordance; the button is hidden entirely when this member is absent.
+     *
+     * Rejecting is a normal outcome — the editor surfaces the error message and
+     * leaves the document untouched.
+     */
+    suggest?(ctx: LayoutAssistContext): Promise<LayoutSuggestionResult>;
+}

package/dist/types/spec-editor/index.d.ts

@@ -19,6 +19,7 @@ export type { DomainSchema, DomainRelation } from './domain/domain-schema';
 export { extractDomainSchema } from './domain/domain-schema';
 export { validateAgainstDomain, extractSelectorIdentifiers, } from './domain/domain-validation';
 export type { SelectorAssistant, SelectorAssistContext, Completion, } from './domain/assistant';
+export type { LayoutAssistant, LayoutAssistContext, LayoutSuggestionResult, LayoutSuggestionDetail, LayoutSuggestionConfidence, LayoutSuggestionOutcome, } from './domain/layout-assistant';
 export { getSelectorKeywordCompletions, getDomainCompletions, createBuiltinCompletionSource, mergeCompletions, MAX_ATOM_COMPLETIONS, } from './domain/completions';
 export type { SpecEditorTheme } from './ui/theme';
 export { lightTheme, darkTheme, themeToCssVars, registerSpecEditorThemes, resolveSpecEditorTheme } from './ui/theme';
@@ -35,5 +36,7 @@ export type { CodeViewProps } from './ui/CodeView';
 export { CodeView } from './ui/CodeView';
 export type { BuilderViewProps } from './ui/BuilderView';
 export { BuilderView } from './ui/BuilderView';
+export type { SuggestionsPanelProps } from './ui/SuggestionsPanel';
+export { SuggestionsPanel } from './ui/SuggestionsPanel';
 export type { SpecEditorProps } from './ui/SpecEditor';
 export { SpecEditor } from './ui/SpecEditor';

package/dist/types/spec-editor/ui/SpecEditor.d.ts

@@ -23,12 +23,18 @@
  * with `assistant.complete()`; `assistant.synthesize` powers the ✨ affordance;
  * `assistant.review()` results are merged into the field diagnostics (debounced,
  * stale-dropped, failures swallowed).
+ *
+ * Layout assistance: `layoutAssistant.suggest` powers the toolbar's Suggest
+ * button. The proposal is applied through `replaceFromYaml` + `emit`, so it is
+ * one undo step, refreshes the builder in place, and re-validates — the same
+ * path a code-view edit takes. Its rationale renders in the suggestions panel.
  */
 import React from 'react';
 import './spec-editor.css';
 import type { Diagnostic } from '../core/types';
 import type { DomainSchema } from '../domain/domain-schema';
 import type { SelectorAssistant } from '../domain/assistant';
+import type { LayoutAssistant } from '../domain/layout-assistant';
 import type { IInputDataInstance } from '../../data-instance/interfaces';
 import { SpecEditorThemeInput } from './theme';
 export interface SpecEditorProps {
@@ -47,6 +53,11 @@ export interface SpecEditorProps {
      */
     theme?: SpecEditorThemeInput;
     selectorAssistant?: SelectorAssistant;
+    /**
+     * Whole-spec suggestion hook. When it provides `suggest`, the toolbar grows a
+     * Suggest button; otherwise nothing is rendered and the editor is unchanged.
+     */
+    layoutAssistant?: LayoutAssistant;
     /** appearance */
     density?: 'compact' | 'comfortable';
     /**

package/dist/types/spec-editor/ui/SuggestionsPanel.d.ts

@@ -0,0 +1,18 @@
+/**
+ * {@link SuggestionsPanel} — the read-only explanation of a
+ * {@link LayoutAssistant} run.
+ *
+ * The suggestion itself has already been applied to the document by the time
+ * this renders; the panel exists so the reasoning isn't thrown away. Each row
+ * shows the suggester's rationale plus two optional generic chips (confidence,
+ * outcome), and result-level `notes` follow the list. Nothing here is
+ * interactive beyond dismissal — accepting or rejecting individual suggestions
+ * would require the suggester to recompose the spec, which is host policy.
+ */
+import React from 'react';
+import type { LayoutSuggestionResult } from '../domain/layout-assistant';
+export interface SuggestionsPanelProps {
+    result: LayoutSuggestionResult;
+    onDismiss(): void;
+}
+export declare const SuggestionsPanel: React.FC<SuggestionsPanelProps>;

package/dist/types/spec-editor/ui/index.d.ts

@@ -26,5 +26,7 @@ export type { CodeViewProps } from './CodeView';
 export { CodeView } from './CodeView';
 export type { BuilderViewProps } from './BuilderView';
 export { BuilderView } from './BuilderView';
+export type { SuggestionsPanelProps } from './SuggestionsPanel';
+export { SuggestionsPanel } from './SuggestionsPanel';
 export type { SpecEditorProps } from './SpecEditor';
 export { SpecEditor } from './SpecEditor';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spytial-core",
-  "version": "4.0.0",
+  "version": "4.0.1",
   "description": "A fully client-side application for SpyTial.",
   "main": "./dist/browser/spytial-core-complete.global.js",
   "types": "./dist/types/index.d.ts",