@tai42/studio-sdk 30.0.0 → 31.0.0

package/src/index.ts

@@ -190,17 +190,39 @@ export { effectiveHidden, hiddenToolNames } from './tool-visibility';
 // -- Tool declared-badge merge (native ∪ overlay) ----------------------------
 export { mergeToolBadges, toolBadgesByName } from './tool-badges';
 
+// -- Text search shared by pickers and filterable lists ----------------------
+export { isBlankSearch, matchesSearch } from './search-match';
+
 // -- Design system -----------------------------------------------------------
 export type { ActionMenuItem, ActionMenuProps } from './components/action-menu';
 export { ActionMenu } from './components/action-menu';
+export type { AgentListQuery, AgentPickerProps } from './components/agent-picker';
+export { AgentPicker } from './components/agent-picker';
 export type { BadgeProps } from './components/badge';
 export { Badge } from './components/badge';
+export type { ChannelListQuery, ChannelPickerProps } from './components/channel-picker';
+export { channelIdentityHint, ChannelPicker } from './components/channel-picker';
 export type { CheckboxProps } from './components/checkbox';
 export { Checkbox } from './components/checkbox';
 export type { ChipGroupProps, ChipOption } from './components/chip-group';
 export { ChipGroup } from './components/chip-group';
+export type { CodeBlockProps } from './components/code-block';
+export { CodeBlock } from './components/code-block';
 export type { ConfirmDialogProps } from './components/confirm-dialog';
 export { ConfirmDialog } from './components/confirm-dialog';
+export type { CopyFieldProps } from './components/copy-field';
+export { CopyField } from './components/copy-field';
+export type {
+  DateRangePickerProps,
+  DateRangePreset,
+  DateRangeValue,
+} from './components/date-range-picker';
+export {
+  DateRangePicker,
+  DEFAULT_DATE_RANGE_PRESETS,
+  formatRangeLabel,
+  normalizeCustomRange,
+} from './components/date-range-picker';
 export type { DialogProps } from './components/dialog';
 export { Dialog } from './components/dialog';
 export { DirtyGuardBoundary, GuardedTabs, useRegisterDirty } from './components/dirty-guard';
@@ -210,6 +232,12 @@ export type { EntityCardGridProps } from './components/entity-card-grid';
 export { EntityCardGrid } from './components/entity-card-grid';
 export type { ErrorBoundaryProps } from './components/error-boundary';
 export { ErrorBoundary } from './components/error-boundary';
+export type { ExecutionKeyPickerProps, ExecutionKeyQuery } from './components/execution-key-picker';
+export {
+  canHoldExecutionKey,
+  ExecutionKeyPicker,
+  isExecutionKeyListEmpty,
+} from './components/execution-key-picker';
 export type {
   ExplorerColumn,
   ExplorerEmptyState,
@@ -225,16 +253,37 @@ export {
   matchesSelectedTags,
   UNTAGGED_TOKEN,
 } from './components/explorer-view';
+export type { ExtensionComboBuilderProps } from './components/extension-combo-builder';
+export { ExtensionComboBuilder } from './components/extension-combo-builder';
+export type { ExtensionKindGroup } from './components/extension-grouping';
+export { groupByKind } from './components/extension-grouping';
+export type { ExtensionPickerProps } from './components/extension-picker';
+export { ExtensionPicker } from './components/extension-picker';
+export type { ExternalLinkButtonProps } from './components/external-link';
+export { ExternalLinkButton, isSafeHttpUrl } from './components/external-link';
 export type { FieldControlProps, FieldProps } from './components/field';
 export { Field, useFieldControl } from './components/field';
+export type { FleetReportProps } from './components/fleet-report';
+export { FleetReport } from './components/fleet-report';
 export type { FormDialogProps } from './components/form-dialog';
 export { FormDialog } from './components/form-dialog';
+export type {
+  HolderHref,
+  HolderListProps,
+  HolderPreviewProps,
+  HolderPreviewState,
+} from './components/holder-list';
+export { HolderList, HolderPreview, previewHolders, useHolderHref } from './components/holder-list';
 export type { NumberInputProps, TextareaProps, TextInputProps } from './components/inputs';
 export { NumberInput, Textarea, TextInput } from './components/inputs';
 export type { JsonDiffProps, JsonDiffRow } from './components/json-diff';
 export { diffJson, JsonDiff } from './components/json-diff';
 export type { JsonTreeProps } from './components/json-tree';
 export { JsonTree } from './components/json-tree';
+export type { HeadingLevel, MarkdownBlock, MarkdownProps } from './components/markdown';
+export { Markdown, parseMarkdown } from './components/markdown';
+export type { OpenTargetOptions, OpenTargetProps } from './components/open-target';
+export { openTargetProps } from './components/open-target';
 export type {
   OverlayDetails,
   OverlayDetailsFieldsProps,
@@ -254,8 +303,13 @@ export type {
   SpinnerProps,
 } from './components/primitives';
 export { Button, Card, EmptyState, ErrorState, Skeleton, Spinner } from './components/primitives';
+export { safeHttpUrl } from './components/primitives';
 export type { RadioGroupProps, RadioOption } from './components/radio-group';
 export { RadioGroup } from './components/radio-group';
+export type { RecycleRollSectionProps } from './components/recycle-roll';
+export { RecycleRollSection } from './components/recycle-roll';
+export type { RevealInputProps } from './components/reveal-input';
+export { RevealInput } from './components/reveal-input';
 export type {
   OverflowAxis,
   OverflowRegionAttributes,
@@ -263,6 +317,11 @@ export type {
   ScrollRegionProps,
 } from './components/scroll-region';
 export { ScrollRegion, useOverflowRegion, useProseScrollRegions } from './components/scroll-region';
+export type {
+  SearchableSelectGroupsProps,
+  SearchableSelectProps,
+} from './components/searchable-select';
+export { SearchableSelect } from './components/searchable-select';
 export type {
   SelectGroup,
   SelectGroupsProps,
@@ -270,73 +329,6 @@ export type {
   SelectProps,
 } from './components/select';
 export { Select } from './components/select';
-export type {
-  NumericColumnProps,
-  TableProps,
-  TableRowProps,
-  TableSectionProps,
-  TDProps,
-  THProps,
-} from './components/table';
-export { Table, TBody, TD, TH, THead, TR } from './components/table';
-export type { TabItem, TabsProps } from './components/tabs';
-export { Tabs } from './components/tabs';
-export type { TagChipsProps, TagsInputProps } from './components/tags';
-export { TagChips, TagsInput } from './components/tags';
-export type {
-  TemplatedTextFieldProps,
-  TemplatedTextInlineProps,
-  TemplatedTextTemplateOption,
-} from './components/templated-text-field';
-export { TemplatedTextField, templatedTextSummary } from './components/templated-text-field';
-export type { TooltipProps } from './components/tooltip';
-export { Tooltip } from './components/tooltip';
-export type { ViewMode, ViewToggleProps } from './components/view-toggle';
-export { useViewMode, ViewToggle } from './components/view-toggle';
-// The canonical whole-row/whole-card "open" affordance: one helper every
-// navigable list surface spreads onto its entry (see the module doc).
-export type { CodeBlockProps } from './components/code-block';
-export { CodeBlock } from './components/code-block';
-export type {
-  DateRangePickerProps,
-  DateRangePreset,
-  DateRangeValue,
-} from './components/date-range-picker';
-export {
-  DateRangePicker,
-  DEFAULT_DATE_RANGE_PRESETS,
-  formatRangeLabel,
-  normalizeCustomRange,
-} from './components/date-range-picker';
-export { ExternalLinkButton, isSafeHttpUrl } from './components/external-link';
-export type { FleetReportProps } from './components/fleet-report';
-export { FleetReport } from './components/fleet-report';
-export type {
-  Folder,
-  FolderBreadcrumbProps,
-  FolderPickerProps,
-  FolderRowProps,
-} from './components/folder-nav';
-export {
-  childFolders,
-  FolderBreadcrumb,
-  folderPathTo,
-  FolderPicker,
-  FolderRow,
-} from './components/folder-nav';
-export type {
-  HolderHref,
-  HolderListProps,
-  HolderPreviewProps,
-  HolderPreviewState,
-} from './components/holder-list';
-export { HolderList, HolderPreview, previewHolders, useHolderHref } from './components/holder-list';
-export type { HeadingLevel, MarkdownBlock, MarkdownProps } from './components/markdown';
-export { Markdown, parseMarkdown } from './components/markdown';
-export type { OpenTargetOptions, OpenTargetProps } from './components/open-target';
-export { openTargetProps } from './components/open-target';
-export type { RecycleRollSectionProps } from './components/recycle-roll';
-export { RecycleRollSection } from './components/recycle-roll';
 export type {
   MediaDocumentProps,
   MediaImageProps,
@@ -353,32 +345,6 @@ export {
 } from './components/served-media';
 export type { StepperProps, StepperStatus, StepperStep } from './components/stepper';
 export { Stepper } from './components/stepper';
-// The marketplace install UI; its directory index lists the published names.
-export * from './marketplace-install';
-// The URL half of the link-safety pair: `isSafeHttpUrl` answers yes/no, this one
-// hands back the parsed URL, so a caller that needs the URL does not re-parse it.
-export type { AgentListQuery, AgentPickerProps } from './components/agent-picker';
-export { AgentPicker } from './components/agent-picker';
-export type { ChannelListQuery, ChannelPickerProps } from './components/channel-picker';
-export { channelIdentityHint, ChannelPicker } from './components/channel-picker';
-export type { CopyFieldProps } from './components/copy-field';
-export { CopyField } from './components/copy-field';
-export type { ExecutionKeyPickerProps, ExecutionKeyQuery } from './components/execution-key-picker';
-export {
-  canHoldExecutionKey,
-  ExecutionKeyPicker,
-  isExecutionKeyListEmpty,
-} from './components/execution-key-picker';
-export type { ExtensionComboBuilderProps } from './components/extension-combo-builder';
-export { ExtensionComboBuilder } from './components/extension-combo-builder';
-export type { ExtensionKindGroup } from './components/extension-grouping';
-export { groupByKind } from './components/extension-grouping';
-export type { ExtensionPickerProps } from './components/extension-picker';
-export { ExtensionPicker } from './components/extension-picker';
-export type { ExternalLinkButtonProps } from './components/external-link';
-export { safeHttpUrl } from './components/primitives';
-export type { RevealInputProps } from './components/reveal-input';
-export { RevealInput } from './components/reveal-input';
 export type { SubjectSectionProps, SubjectTargetOption } from './components/subject-section';
 export {
   buildSubject,
@@ -387,16 +353,43 @@ export {
   toSubjectTargetOptions,
   useSubjectFields,
 } from './components/subject-section';
+export type {
+  NumericColumnProps,
+  TableProps,
+  TableRowProps,
+  TableSectionProps,
+  TDProps,
+  THProps,
+} from './components/table';
+export { Table, TBody, TD, TH, THead, TR } from './components/table';
+export type { TabItem, TabsProps } from './components/tabs';
+export { Tabs } from './components/tabs';
+export type { TagChipsProps, TagsInputProps } from './components/tags';
+export { TagChips, TagsInput } from './components/tags';
+export type {
+  TemplatedTextFieldProps,
+  TemplatedTextInlineProps,
+  TemplatedTextTemplateOption,
+} from './components/templated-text-field';
+export { TemplatedTextField, templatedTextSummary } from './components/templated-text-field';
 export type { TokenName } from './components/tokens';
 export { TOKEN_NAMES } from './components/tokens';
 export type { ToolListQuery, ToolPickerProps } from './components/tool-picker';
 export { BADGES_NOTE, ToolPicker } from './components/tool-picker';
+export type { TooltipProps } from './components/tooltip';
+export { Tooltip } from './components/tooltip';
 export type {
   VersionHistoryEntry,
   VersionHistoryPanelProps,
 } from './components/version-history-panel';
 export { VersionHistoryPanel } from './components/version-history-panel';
+export type { ViewMode, ViewToggleProps } from './components/view-toggle';
+export { useViewMode, ViewToggle } from './components/view-toggle';
 
+// -- Whole-module re-exports (each module's own index lists its published names) --
+// The marketplace install UI and the tool-organization folder tree.
+export * from './marketplace-install';
+export * from './tool-organization';
 // -- Iconography (the only sanctioned marks; Unicode glyphs are banned) -------
 export type { IconComponent, IconProps } from './components/icons';
 export {
@@ -472,6 +465,7 @@ export type {
   SchemaFormProps,
   SecretRef,
   SecretRefFieldProps,
+  UseTemplatedTextCatalog,
 } from './schema-form';
 export {
   dateRangePairs,
@@ -485,15 +479,25 @@ export {
   ExpressionFieldContext,
   fieldDrawingOrder,
   isFieldVisible,
+  NoFiniteValueError,
   RecordEntryRendererContext,
   resolveRef,
   SchemaForm,
   SecretRefField,
+  // The stored-template source for schema-built templated-text fields: a host
+  // mounts a hook here that returns the template catalog, so those fields offer
+  // stored templates beside inline content.
+  TemplatedTextCatalogContext,
   validateAgainstSchema,
 } from './schema-form';
 
 // -- Schema-editor (validated JSON-Schema authoring control) -----------------
-export type { SchemaEditorChange, SchemaEditorProps, SchemaLintResult } from './schema-editor';
+export type {
+  SchemaEditorChange,
+  SchemaEditorDraft,
+  SchemaEditorProps,
+  SchemaLintResult,
+} from './schema-editor';
 export { lintSchemaText, SchemaEditor } from './schema-editor';
 
 // -- State-binding editor (the one binding shape every door authors, plugin doors included) --

package/src/plugin/version.ts

@@ -26,7 +26,7 @@
  *    authoring docs state it: stylesheet injection is a host capability, so a
  *    deployment pairs the Studio host with plugins built for it.
  */
-export const STUDIO_PLUGIN_API_VERSION = 2;
+export const STUDIO_PLUGIN_API_VERSION = 3;
 
 export interface VersionGateResult {
   readonly ok: boolean;

package/src/schema-editor/SchemaEditor.tsx

@@ -31,14 +31,20 @@ import { SchemaForm } from '../schema-form/SchemaForm';
 import type { JsonSchema } from '../schema-form/types';
 import { lintSchemaText } from './lint';
 
-/** What {@link SchemaEditor} reports up on every edit. */
-export interface SchemaEditorChange {
+/** The parsed schema and its validity: what a host keeps of a {@link SchemaEditor}. */
+export interface SchemaEditorDraft {
   /** The authored schema dict when valid and non-empty; `null` when the editor is empty. */
   readonly schema: Record<string, unknown> | null;
   /** False when the text is non-empty but unparseable or failing lint — gate submit on this. */
   readonly valid: boolean;
 }
 
+/** What {@link SchemaEditor} reports up on every edit. */
+export interface SchemaEditorChange extends SchemaEditorDraft {
+  /** The editor's text as typed, so a host can hold a draft the editor rejects. */
+  readonly text: string;
+}
+
 export interface SchemaEditorProps {
   /** The schema dict to seed the editor with, or `null` for an empty editor. */
   readonly value: Record<string, unknown> | null;
@@ -162,7 +168,7 @@ export function SchemaEditor({
   const emit = (nextText: string): void => {
     setText(nextText);
     const next = lintSchemaText(nextText, requireTitle);
-    onChange({ schema: next.valid ? next.schema : null, valid: next.valid });
+    onChange({ schema: next.valid ? next.schema : null, valid: next.valid, text: nextText });
   };
 
   return (

package/src/schema-editor/index.ts

@@ -1,9 +1,9 @@
 /**
  * Schema-editor — the shared, validated JSON-Schema authoring control. Public
- * surface: the `SchemaEditor` component, its change type, and the pure lint helper
+ * surface: the `SchemaEditor` component, its change and draft types, and the pure lint helper
  * consumers reuse to pre-check a stored schema.
  */
 export type { SchemaLintResult } from './lint';
 export { lintSchemaText } from './lint';
-export type { SchemaEditorChange, SchemaEditorProps } from './SchemaEditor';
+export type { SchemaEditorChange, SchemaEditorDraft, SchemaEditorProps } from './SchemaEditor';
 export { SchemaEditor } from './SchemaEditor';

package/src/schema-form/array-field.tsx

@@ -18,6 +18,7 @@ import { defaultValueForSchema } from './default-value';
 import { FieldGroup } from './field-group';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
+import { useSeedingAction } from './seeding-action';
 import type { FieldWords, JsonSchema, SchemaFormErrors } from './types';
 
 export function ArrayField({
@@ -49,8 +50,10 @@ export function ArrayField({
   const itemLabel = (index: number): string =>
     (words?.itemLabel ?? 'Item {n}').split('{n}').join(String(index + 1));
   const list = Array.isArray(value) ? (value as unknown[]) : [];
+  const add = useSeedingAction(items);
   const addItem = (): void => {
-    onChange([...list, newItemValue(items, root)]);
+    const item = add.seed(() => newItemValue(items, root));
+    if (item.ok) onChange([...list, item.value]);
   };
   const removeItem = (index: number): void => {
     onChange(list.filter((_, position) => position !== index));
@@ -61,7 +64,12 @@ export function ArrayField({
   const changeFor = useKeyedCallbacks<number, unknown>(setItem, list.keys());
 
   return (
-    <FieldGroup heading={heading} description={description} error={error} atRoot={false}>
+    <FieldGroup
+      heading={heading}
+      description={description}
+      error={add.failure ?? error}
+      atRoot={false}
+    >
       {list.length === 0 ? (
         <span className="tai-field-hint">{words?.noItems ?? 'No items'}</span>
       ) : null}

package/src/schema-form/classify.ts

@@ -18,7 +18,12 @@ import {
   variantLabel,
   variantTag,
 } from './resolve';
-import { expressionAnnotation, mediaUpload } from './string-annotations';
+import {
+  expressionAnnotation,
+  isTemplatedText,
+  mediaUpload,
+  withSiteExpression,
+} from './string-annotations';
 import type { FormControl, FormInputMode, JsonSchema } from './types';
 
 function firstString(...values: readonly unknown[]): string | undefined {
@@ -103,7 +108,8 @@ function classifyEnum(
   };
 }
 
-// anyOf/oneOf union normalization.
+// anyOf/oneOf union normalization. The wrapper is the property site, so its
+// expression annotation is carried onto every member before the members classify.
 function classifyUnion(
   resolved: JsonSchema,
   members: readonly JsonSchema[],
@@ -111,7 +117,9 @@ function classifyUnion(
   title: string | undefined,
   description: string | undefined,
 ): ClassifiedField {
-  const nonNull = members.filter((member) => !isNullSchema(resolveRef(member, root)));
+  const nonNull = members
+    .filter((member) => !isNullSchema(resolveRef(member, root)))
+    .map((member) => withSiteExpression(member, resolved));
   const nullable = nonNull.length !== members.length;
   const soleNonNull = nonNull[0];
   if (soleNonNull === undefined) {
@@ -135,7 +143,7 @@ function classifyUnion(
     return { label: variantLabel(member, index, tag, root), tag, schema: member };
   });
   return {
-    model: { kind: 'union', variants, discriminator },
+    model: { kind: 'union', variants, discriminator, members },
     nullable,
     schema: resolved,
     title,
@@ -157,16 +165,10 @@ function classifySoleUnionMember(
   // that land on the OUTER null-union wrapper of an OPTIONAL field would
   // otherwise be lost when delegating to the inner string member, silently
   // degrading an optional upload field to a plain text box. Re-detect them on
-  // the wrapper and attach to the inner string model. The expression
-  // annotation gets the same treatment for the same reason: an optional
-  // annotated field must keep its editor door.
+  // the wrapper and attach to the inner string model.
   const model =
     inner.model.kind === 'string'
-      ? {
-          ...inner.model,
-          media: inner.model.media ?? mediaUpload(resolved),
-          expression: inner.model.expression ?? expressionAnnotation(resolved),
-        }
+      ? { ...inner.model, media: inner.model.media ?? mediaUpload(resolved) }
       : inner.model;
   return {
     model,
@@ -373,7 +375,7 @@ function classifyObject(
   const properties: (readonly [string, JsonSchema])[] = Object.entries(resolved.properties);
   const required = new Set(resolved.required ?? []);
   return {
-    model: { kind: 'object', properties, required },
+    model: { kind: 'object', properties, required, shape: resolved.properties },
     nullable,
     schema: resolved,
     title,
@@ -462,13 +464,37 @@ function classifyByType(
   }
 }
 
+/**
+ * A property typed as the platform's templated text. A node carrying the type's
+ * `x-tai42-templated-text` mark IS the type's schema, so its title and description
+ * name the TYPE, never the field: only a property site apart from it — the `$ref`
+ * pointing at the type, or a union wrapper (the union path keeps the wrapper's
+ * words) — labels the field. An inlined type node is therefore word-less here, and
+ * the field falls back to its property key. The expression annotation is read off the
+ * resolved node, which carries the property site's annotation (see {@link classifySchema}).
+ */
+function classifyTemplatedText(raw: JsonSchema, resolved: JsonSchema): ClassifiedField {
+  const site = isTemplatedText(raw) ? undefined : raw;
+  return {
+    model: { kind: 'templated-text', expression: expressionAnnotation(resolved) },
+    nullable: false,
+    schema: resolved,
+    title: firstString(site?.title),
+    description: firstString(site?.description),
+  };
+}
+
 /**
  * Classify a schema node (resolving `$ref` first). `wrapper` metadata (a
  * ref-site title/description) is threaded down so a `{ $ref, title }` or a
- * null-union wrapper keeps its property-level label.
+ * null-union wrapper keeps its property-level label. The `x-tai42-expression`
+ * annotation beside a `$ref` is a property-site key that `$ref` resolution would
+ * drop, so it is carried onto the resolved node; a referenced definition that
+ * carries its own annotation keeps it.
  */
 export function classifySchema(raw: JsonSchema, root: JsonSchema): ClassifiedField {
-  const resolved = resolveRef(raw, root);
+  const resolved = withSiteExpression(resolveRef(raw, root), raw);
+  if (isTemplatedText(resolved)) return classifyTemplatedText(raw, resolved);
   const title = firstString(raw.title, resolved.title);
   const description = firstString(raw.description, resolved.description);
 

package/src/schema-form/collapsed-object-field.tsx

@@ -0,0 +1,56 @@
+/**
+ * A level of a self-referencing definition that the value does not hold: the
+ * field's labelled group with one Add button, which seeds the definition's value
+ * for that level. Drawn instead of the level's fields so the nesting stops at the
+ * data (see `ExpandedShapesContext`).
+ */
+import type { ReactNode } from 'react';
+
+import { Button } from '../components/primitives';
+import { defaultValueForSchema } from './default-value';
+import { FieldGroup } from './field-group';
+import { useSeedingAction } from './seeding-action';
+import type { JsonSchema } from './types';
+
+export function CollapsedObjectField({
+  heading,
+  description,
+  error,
+  definition,
+  shape,
+  root,
+  onChange,
+}: {
+  heading: string;
+  description: string | undefined;
+  error: string | undefined;
+  /** The ref-resolved object schema the Add button seeds. */
+  definition: JsonSchema;
+  /** The level's object model `shape`, the identity a failure belongs to. */
+  shape: object;
+  root: JsonSchema;
+  onChange: (value: unknown) => void;
+}): ReactNode {
+  const add = useSeedingAction(shape);
+  return (
+    <FieldGroup
+      heading={heading}
+      description={description}
+      error={add.failure ?? error}
+      atRoot={false}
+    >
+      <div>
+        <Button
+          type="button"
+          variant="secondary"
+          onClick={() => {
+            const level = add.seed(() => defaultValueForSchema(definition, root));
+            if (level.ok) onChange(level.value);
+          }}
+        >
+          Add
+        </Button>
+      </div>
+    </FieldGroup>
+  );
+}

package/src/schema-form/context.ts

@@ -1,12 +1,14 @@
 /**
  * Ambient React contexts for the schema-form tree: the optional argument
  * completion provider, the default media-upload byte cap, the record-entry value
- * renderer, and the expression-field door. A field deep in the tree reads these
+ * renderer, the expression-field door, and the object shapes being drawn above a
+ * field. A field deep in the tree reads these
  * here rather than every intermediate node drilling the prop.
  */
 import type { ComponentType, ReactNode } from 'react';
 import { createContext } from 'react';
 
+import type { TemplatedTextCatalog } from '../state-binding/types';
 import { DEFAULT_MAX_UPLOAD_BYTES } from './media';
 import type { CompletionProvider } from './SchemaForm';
 import type { JsonSchema } from './types';
@@ -15,6 +17,14 @@ import type { JsonSchema } from './types';
 // tree reads it here rather than every intermediate node drilling the prop.
 export const CompletionProviderContext = createContext<CompletionProvider | undefined>(undefined);
 
+/**
+ * The object shapes (an object model's `shape`) being drawn by the fields above
+ * this one. An object field whose shape is already here is a definition nested
+ * inside itself; it draws its fields only when its value holds that level, so a
+ * self-referencing schema draws to the depth of its data rather than forever.
+ */
+export const ExpandedShapesContext = createContext<ReadonlySet<object>>(new Set());
+
 // Ambient default upload cap for the whole form; a media field reads it here so
 // intermediate object/array nodes never drill the prop.
 export const MaxUploadBytesContext = createContext<number>(DEFAULT_MAX_UPLOAD_BYTES);
@@ -147,3 +157,25 @@ export type ExpressionFieldComponent = ComponentType<ExpressionFieldProps>;
 export const ExpressionFieldContext = createContext<ExpressionFieldComponent | undefined>(
   undefined,
 );
+
+/**
+ * The hook a host supplies so a form's templated-text fields can offer stored
+ * templates: it returns the catalog (the template ids plus the storage-presence and
+ * fetch state) the field's stored-template picker reads. The form holds no data edge,
+ * so the host owns the fetch; a field calls the hook only when it renders, so a form
+ * without a templated-text field never fetches the catalog.
+ *
+ * It is a HOOK, called on every render of a templated-text field, so the injected
+ * reference must be stable (a module-level function).
+ */
+export type UseTemplatedTextCatalog = () => TemplatedTextCatalog | undefined;
+
+const useNoTemplatedTextCatalog: UseTemplatedTextCatalog = () => undefined;
+
+/**
+ * The ambient stored-template source for the whole form. Absent (the default), a
+ * templated-text field gets no catalog, as every `TemplatedTextField` given none:
+ * the stored source offers no templates and inline content is authored as usual.
+ */
+export const TemplatedTextCatalogContext =
+  createContext<UseTemplatedTextCatalog>(useNoTemplatedTextCatalog);