Class PerspectiveScriptGrounding
Produces the AI grounding for one Perspective script-editing surface: the framing string that
describes where the body lives, the read tools the agent can call for anything the framing does
not carry, and the @-reference sources the prompt offers.
Construct one per editor and hand it to PerspectiveScriptAssistMounter.attach(ExtensionFunctionPanel, PerspectiveScriptGrounding, Supplier), which mounts
the "Ask AI" button. This class decides what the agent knows; the mounter decides how that
reaches it.
The component the body is written against is fixed when its editor window opens: its name, type
and target count all describe that component, never whatever is selected when the prompt is
sent. The editor windows are non-modal, so the Designer's selection can move while one is open;
reading the type off the live selection would name one component with another's type. The
message type code and the checked listen scopes, by contrast, are live widget state, re-read on
the Event Dispatch Thread at prompt time. Nothing here blocks — the component registry is held
locally in the Designer, so the reads are cheap enough to sit inside the framework's synchronous
context assembly. Anything that would cost a Gateway round trip belongs in
PerspectivePropertyTools instead, which the agent calls from its own thread when it needs it.
Facts that cannot be read degrade to unstated rather than to an error, so an assistant opened on a multi-selection, on a component whose type is not in the registry, or before a message type has been typed still answers.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final recordWhat an editor window was opened on, captured once when the window is built — not when an editor panel inside it is built, since those are created lazily, after the selection may already have moved. -
Constructor Summary
ConstructorsConstructorDescriptionPerspectiveScriptGrounding(DesignAdapter adapter, Supplier<Optional<ComponentPath>> primaryComponentPath, PerspectiveScriptGrounding.TargetSnapshot targetSnapshot) -
Method Summary
Modifier and TypeMethodDescriptioncallerContextFor(PerspectiveScriptSurface surface) The framing for a surface that needs no facts beyond the component it is defined on — custom methods and extension functions.componentCallerContext(Supplier<String> surfaceFraming) The framing for a component script surface Perspective does not define — one a module adds to the scripts editor through aScriptCategoryProvider, such as an AI Chat's Agent Tools.messageHandlerCallerContext(Supplier<@Nullable String> messageType, Supplier<List<String>> listenScopes) The framing for a component message handler, adding the routing that decides whether the body ever runs.The@-reference sources every scripting surface offers: tags, the components of the current view, and Perspective property paths.propertyChangeCallerContext(Supplier<@Nullable String> propertyDescription) The framing for a property change script, adding the property whose change runs the body.tools()
-
Constructor Details
-
PerspectiveScriptGrounding
public PerspectiveScriptGrounding(DesignAdapter adapter, Supplier<Optional<ComponentPath>> primaryComponentPath, PerspectiveScriptGrounding.TargetSnapshot targetSnapshot) - Parameters:
adapter- the Perspective design adapter for the workspace the editor belongs to; the source of the view path and of the read tools' view of the component graph.primaryComponentPath- the anchor component's path as the editor window recorded it when it opened. Typicallycontext::getPrimaryComponentPathor the editor frame's own accessor.targetSnapshot- the anchor component's type and the target count, captured when the editor window opened alongsideprimaryComponentPath.
-
-
Method Details
-
callerContextFor
The framing for a surface that needs no facts beyond the component it is defined on — custom methods and extension functions. Message handlers and property change scripts must usemessageHandlerCallerContext(Supplier, Supplier)andpropertyChangeCallerContext(Supplier)instead: without their live configuration, a message handler would be framed as having no type code and no listen scope, telling the agent that nothing can ever reach it.- Parameters:
surface- the surface being framed;PerspectiveScriptSurface.CUSTOM_METHODorPerspectiveScriptSurface.EXTENSION_FUNCTION.- Returns:
- a supplier building the framing on each prompt.
- Throws:
IllegalArgumentException- ifsurfaceis one that has a variant of its own.
-
messageHandlerCallerContext
public Supplier<String> messageHandlerCallerContext(Supplier<@Nullable String> messageType, Supplier<List<String>> listenScopes) The framing for a component message handler, adding the routing that decides whether the body ever runs.- Parameters:
messageType- the message type code as currently typed; blank until the user fills it in.listenScopes- the currently checked listen scopes, as"session"/"page"/"view". An empty list is a meaningful state — nothing reaches the handler — and is framed as such.- Returns:
- a supplier re-reading the handler's form on each prompt.
-
propertyChangeCallerContext
The framing for a property change script, adding the property whose change runs the body.- Parameters:
propertyDescription- a human description of the triggering property, e.g.Button1.props.text.- Returns:
- a supplier re-reading the property on each prompt.
-
componentCallerContext
The framing for a component script surface Perspective does not define — one a module adds to the scripts editor through aScriptCategoryProvider, such as an AI Chat's Agent Tools. The module describes its own surface; this adds whatselfis, its members, and the view it is on, exactly as the built-in surfaces state them.- Parameters:
surfaceFraming- the module's description of the surface: who calls the body, what it receives and what it must return. Re-read on each prompt, so it may read live form state.- Returns:
- a supplier building the combined framing on each prompt.
-
tools
- Returns:
- the read-only Perspective tools every scripting surface offers — the selection, the view structure, and the component graph with its bindings, scripts and property values.
-
promptAssists
The@-reference sources every scripting surface offers: tags, the components of the current view, and Perspective property paths. The tag browser is the platform's own, taken default-configured offai.promptAssists()the way the binding and property editors take theirs; only the two Perspective-specific assists are constructed here.- Parameters:
ai- the Designer AI context the button will be mounted against, the owner of the shared platform assists.- Returns:
- the assists, in the order the
@-popup should present them.
-