@tai42/studio-sdk 20.0.0 → 22.0.0

package/src/schema-form/field-model.ts

@@ -5,7 +5,7 @@
  * validator import the vocabulary without pulling in classification code.
  */
 import type { EnumOption } from './resolve';
-import type { JsonSchema } from './types';
+import type { FormControl, FormInputMode, JsonSchema } from './types';
 
 /**
  * How a string field accepts binary content as a JSON-serializable string.
@@ -115,10 +115,28 @@ export interface UnionVariant {
 /** The renderer-facing classification of a schema node. */
 export type FieldModel =
   | { readonly kind: 'const'; readonly value: unknown }
-  | { readonly kind: 'enum'; readonly options: readonly EnumOption[] }
+  | {
+      readonly kind: 'enum';
+      readonly options: readonly EnumOption[];
+      /** The `control` keyword off the property: `'chips'` draws the choice as a
+       *  chip grid in place of the radio/select; `undefined` keeps the default. */
+      readonly control: FormControl | undefined;
+    }
   | {
       readonly kind: 'string';
       readonly format: string | undefined;
+      /** The input kind (keyboard / native control) this string draws, from the
+       *  schema's `inputMode` keyword; `undefined` for a plain text box. It
+       *  draws, it does not validate, and it outranks `format` for the control. */
+      readonly inputMode: FormInputMode | undefined;
+      /** True when the `control` keyword is `'textarea'`: draw a multi-line text
+       *  control instead of a single-line box. It draws, it does not validate. */
+      readonly multiline: boolean;
+      /** The `maxLength`/`minLength` JSON-Schema bounds, drawn on the control (a
+       *  native cap plus a live counter when `maxLength` is set) and enforced by
+       *  the validator. `undefined` leaves that bound unconstrained. */
+      readonly maxLength: number | undefined;
+      readonly minLength: number | undefined;
       /** Present when media annotations opt the field into the upload control. */
       readonly media: MediaUpload | undefined;
       /** Present when a well-formed `x-tai42-expression` annotation opts the
@@ -138,6 +156,10 @@ export type FieldModel =
       // `array` field — a multi-select needs a known option set to draw.
       readonly kind: 'multiselect';
       readonly options: readonly EnumOption[];
+      /** The `control` keyword off the property: `'chips'` draws the multi-select
+       *  as a toggle-chip grid in place of the checkbox group; `undefined` keeps
+       *  the default. */
+      readonly control: FormControl | undefined;
     }
   | {
       readonly kind: 'object';

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

@@ -41,6 +41,14 @@ interface FieldNodeProps {
   readonly markRequired?: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
+  /**
+   * Per-field picker placeholders keyed by property name, handed to an OBJECT node so
+   * its direct `enum`-select children draw their placeholder. Carried by the root form
+   * only; nested objects receive none.
+   */
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  /** This field's own picker placeholder, when it draws as an `enum` select. */
+  readonly choiceLabel?: string;
 }
 
 function labelText(explicit: string | undefined, label: string | undefined): string {
@@ -73,6 +81,8 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
     required,
     errors,
     idPrefix,
+    fieldWording: props.fieldWording,
+    choiceLabel: props.choiceLabel,
   });
 }
 
@@ -90,6 +100,8 @@ interface RenderFieldArgs {
   readonly required: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  readonly choiceLabel?: string;
 }
 
 /** Render the field component matching the classified model kind. */
@@ -126,6 +138,7 @@ function renderField(args: RenderFieldArgs): ReactNode {
           model={model}
           value={value}
           onChange={onChange}
+          choiceLabel={args.choiceLabel}
         />
       );
     case 'string':
@@ -135,6 +148,10 @@ function renderField(args: RenderFieldArgs): ReactNode {
           description={description}
           error={error}
           format={model.format}
+          inputMode={model.inputMode}
+          multiline={model.multiline}
+          maxLength={model.maxLength}
+          minLength={model.minLength}
           media={model.media}
           expression={model.expression}
           date={model.date}
@@ -187,6 +204,7 @@ function renderCompositeField(
   model: Extract<FieldModel, { kind: 'array' | 'object' | 'record' | 'union' }>,
 ): ReactNode {
   const { heading, description, error, root, value, onChange, path, errors, idPrefix } = args;
+  const { fieldWording } = args;
   switch (model.kind) {
     case 'array':
       return (
@@ -216,6 +234,7 @@ function renderCompositeField(
             errors={errors}
             idPrefix={idPrefix}
             skip={undefined}
+            fieldWording={fieldWording}
           />
         </FieldGroup>
       );

package/src/schema-form/index.ts

@@ -38,12 +38,21 @@ export type {
 } from './context';
 export { RecordEntryRendererContext } from './context';
 export { ExpressionFieldContext } from './context';
+export type { DateRangePair } from './date-range-field';
+export { dateRangePairs } from './date-range-field';
 export { defaultValueForSchema } from './default-value';
 export { resolveRef } from './resolve';
 export type { CompletionProvider, SchemaFormProps } from './SchemaForm';
 export { SchemaForm } from './SchemaForm';
 export type { SecretRef, SecretRefFieldProps } from './SecretRefField';
 export { SecretRefField } from './SecretRefField';
-export type { Discriminator, JsonSchema, JsonSchemaType, SchemaFormErrors } from './types';
+export type {
+  Discriminator,
+  FormControl,
+  FormInputMode,
+  JsonSchema,
+  JsonSchemaType,
+  SchemaFormErrors,
+} from './types';
 export { validateAgainstSchema } from './validate';
 export { isFieldVisible } from './visibility';

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

@@ -8,6 +8,7 @@
 import type { ReactNode } from 'react';
 
 import { Checkbox } from '../components/checkbox';
+import { ChipGroup } from '../components/chip-group';
 import { Field } from '../components/field';
 import type { FieldModel } from './field-model';
 
@@ -38,6 +39,26 @@ export function MultiSelectField({
       .filter((candidate) => next.includes(candidate));
     onChange(ordered);
   };
+
+  // `control: chips` draws the multi-select as a toggle-chip grid in place of the
+  // checkbox group. The chips emit the selection in the OPTIONS' declared order.
+  if (model.control === 'chips') {
+    return (
+      <Field label={heading} description={description} error={error} group>
+        <ChipGroup
+          mode="multi"
+          options={model.options.map((option) => ({
+            value: String(option.value),
+            label: option.label,
+          }))}
+          value={selected}
+          onValueChange={(next) => {
+            onChange([...next]);
+          }}
+        />
+      </Field>
+    );
+  }
   return (
     <Field label={heading} description={description} error={error} group>
       {model.options.map((option, index) => {

package/src/schema-form/object-fields.tsx

@@ -6,6 +6,7 @@
  */
 import type { ReactNode } from 'react';
 
+import { DateRangeField, dateRangePairs } from './date-range-field';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
@@ -26,6 +27,7 @@ export function ObjectFields({
   idPrefix,
   skip,
   markRequired = false,
+  fieldWording,
 }: {
   properties: readonly (readonly [string, JsonSchema])[];
   requiredKeys: ReadonlySet<string>;
@@ -38,6 +40,12 @@ export function ObjectFields({
   skip: string | undefined;
   /** Mark each required property's label with the DS required marker. */
   markRequired?: boolean;
+  /**
+   * Per-property picker placeholders, keyed by property name. Handed to the root form's
+   * object only; a property whose `enum` draws as a select shows its entry's
+   * `choiceLabel` as the select placeholder. Absent for nested objects.
+   */
+  fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
   const changeFor = useKeyedCallbacks<string, unknown>(
@@ -46,14 +54,39 @@ export function ObjectFields({
     },
     properties.map(([name]) => name),
   );
+  // A drawable date-range pair renders as ONE DateRangeField at the START's slot; the
+  // END is skipped. The pairing is `dateRangePairs`, the one definition every surface
+  // shares. Properties here are one page's, so the "same page" rule holds by construction.
+  const pairs = dateRangePairs(properties);
+  const pairByStart = new Map(pairs.map((pair) => [pair.startName, pair]));
+  const skippedEnds = new Set(pairs.map((pair) => pair.endName));
+  const childPathOf = (name: string): string => (path === '' ? name : `${path}.${name}`);
   return (
     <>
       {properties.map(([name, propSchema]) => {
         if (skip !== undefined && name === skip) return null;
+        if (skippedEnds.has(name)) return null;
         // A field hidden by its `visibleWhen` predicate (scope B) is not rendered; the
         // validator skips it in step, so a hidden field is neither shown nor required.
         if (!isFieldVisible(propSchema, obj)) return null;
-        const childPath = path === '' ? name : `${path}.${name}`;
+        const pair = pairByStart.get(name);
+        if (pair !== undefined) {
+          return (
+            <DateRangeField
+              key={name}
+              pair={pair}
+              startValue={obj[pair.startName]}
+              endValue={obj[pair.endName]}
+              startRequired={requiredKeys.has(pair.startName)}
+              endRequired={requiredKeys.has(pair.endName)}
+              markRequired={markRequired}
+              startError={errors?.[childPathOf(pair.startName)]}
+              endError={errors?.[childPathOf(pair.endName)]}
+              onChangeStart={changeFor(pair.startName)}
+              onChangeEnd={changeFor(pair.endName)}
+            />
+          );
+        }
         return (
           <FieldNode
             key={name}
@@ -61,12 +94,13 @@ export function ObjectFields({
             root={root}
             value={obj[name]}
             onChange={changeFor(name)}
-            path={childPath}
+            path={childPathOf(name)}
             label={name}
             required={requiredKeys.has(name)}
             markRequired={markRequired}
             errors={errors}
             idPrefix={idPrefix}
+            choiceLabel={fieldWording?.[name]?.choiceLabel}
           />
         );
       })}

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

@@ -31,12 +31,17 @@ import { CompletionProviderContext, ExpressionFieldContext } from './context';
 import type { DateConstraints, ExpressionAnnotation, MediaUpload } from './field-model';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
+import type { FormInputMode } from './types';
 
 export function StringField({
   heading,
   description,
   error,
   format,
+  inputMode,
+  multiline,
+  maxLength,
+  minLength,
   media,
   expression,
   date,
@@ -49,6 +54,10 @@ export function StringField({
   description: string | undefined;
   error: string | undefined;
   format: string | undefined;
+  inputMode: FormInputMode | undefined;
+  multiline: boolean;
+  maxLength: number | undefined;
+  minLength: number | undefined;
   media: MediaUpload | undefined;
   expression: ExpressionAnnotation | undefined;
   date: DateConstraints | undefined;
@@ -57,6 +66,7 @@ export function StringField({
   required: boolean;
   onChange: (value: unknown) => void;
 }): ReactNode {
+  const control = stringControl(format, inputMode);
   const completionProvider = useContext(CompletionProviderContext);
   const expressionField = useContext(ExpressionFieldContext);
   const current = typeof value === 'string' ? value : '';
@@ -114,24 +124,58 @@ export function StringField({
           onChange={emit}
           provider={completionProvider}
         />
+      ) : multiline ? (
+        // `control: textarea` draws a multi-line control; the length bounds draw
+        // natively, and a live counter shows the maximum (below).
+        <Textarea
+          maxLength={maxLength}
+          minLength={minLength}
+          value={current}
+          onChange={(event) => {
+            emit(event.target.value);
+          }}
+        />
       ) : (
         <TextInput
-          type={stringInputType(format)}
+          type={control.type}
+          // The keyboard hint for a `numeric`/`decimal` mode (a text box with a
+          // numeric/decimal keyboard); `undefined` for every other control, which
+          // selects its kind through `type` instead.
+          inputMode={control.inputMode}
           // A native date control enforces its inclusive bounds (scope C); on a
           // non-date input the browser ignores these, and the validator enforces the
           // rest (unavailable days, range span) that the control cannot draw.
           min={date?.min}
           max={date?.max}
+          // The length bounds draw natively (the control caps input at `maxLength`)
+          // and the validator enforces them; a counter shows the maximum (below).
+          maxLength={maxLength}
+          minLength={minLength}
           value={current}
           onChange={(event) => {
             emit(event.target.value);
           }}
         />
       )}
+      {/* The live length counter, shown whenever a maximum is declared — on both the
+          text box and the text area. It counts code points, matching the validator's
+          own `maxLength` check. */}
+      {completionProvider === undefined && maxLength !== undefined ? (
+        <LengthCounter current={current} max={maxLength} />
+      ) : null}
     </Field>
   );
 }
 
+/** The `n / max` length hint under a bounded string control. */
+function LengthCounter({ current, max }: { current: string; max: number }): ReactNode {
+  return (
+    <p className="tai-field-hint" style={{ margin: 0 }} aria-live="polite">
+      {`${String(Array.from(current).length)} / ${String(max)}`}
+    </p>
+  );
+}
+
 /**
  * A string field backed by argument completions. Split out so its memoised
  * hooks stay unconditional (they cannot live behind the provider check in
@@ -360,3 +404,30 @@ function stringInputType(format: string | undefined): string {
   if (format === undefined) return 'text';
   return FORMAT_INPUT_TYPES[format] ?? 'text';
 }
+
+/** The native control each `inputMode` draws. `tel`/`email`/`url` select the
+ *  matching input `type`; `numeric`/`decimal` keep a text box and set the HTML
+ *  `inputmode` keyboard hint; `text` is a plain text box. */
+const INPUT_MODE_CONTROLS: Record<
+  FormInputMode,
+  { readonly type: string; readonly inputMode: 'numeric' | 'decimal' | undefined }
+> = {
+  text: { type: 'text', inputMode: undefined },
+  numeric: { type: 'text', inputMode: 'numeric' },
+  decimal: { type: 'text', inputMode: 'decimal' },
+  tel: { type: 'tel', inputMode: undefined },
+  email: { type: 'email', inputMode: undefined },
+  url: { type: 'url', inputMode: undefined },
+};
+
+// The native control for a string field: the `inputMode` keyword OUTRANKS
+// `format` when present; otherwise the format mapping stands as before. The value
+// is always the typed string — `numeric`/`decimal` set only the keyboard, never a
+// number coercion.
+function stringControl(
+  format: string | undefined,
+  inputMode: FormInputMode | undefined,
+): { readonly type: string; readonly inputMode: 'numeric' | 'decimal' | undefined } {
+  if (inputMode !== undefined) return INPUT_MODE_CONTROLS[inputMode];
+  return { type: stringInputType(format), inputMode: undefined };
+}

package/src/schema-form/types.ts

@@ -11,6 +11,24 @@
 export type JsonSchemaType =
   'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
 
+/**
+ * The input KIND a `string` field collects, drawn as the matching keyboard or
+ * native control. The vocabulary is the HTML `inputmode`/control naming of the
+ * concept: `numeric`/`decimal` set a text box's keyboard hint; `tel`/`email`/`url`
+ * select the matching native control. It draws, it does not validate.
+ */
+export type FormInputMode = 'text' | 'numeric' | 'decimal' | 'tel' | 'email' | 'url';
+
+/**
+ * The CONTROL a surface draws for a property in place of the default for the
+ * property's shape. `chips` draws a choice (a `string` with an `enum`, or an
+ * `array` of such strings) as a tap-to-select chip grid instead of the
+ * radio/select or checkbox group. `textarea` draws a `string` as a multi-line
+ * text control instead of a single-line box. It changes what is DRAWN, never what
+ * is accepted — the value and its validation stay the property's own.
+ */
+export type FormControl = 'chips' | 'textarea';
+
 /** A Pydantic-style discriminated-union tag: which property selects the variant. */
 export interface Discriminator {
   readonly propertyName: string;
@@ -61,6 +79,26 @@ export interface JsonSchema {
   readonly minItems?: number;
   readonly maxItems?: number;
   readonly pattern?: string;
+  /**
+   * The input KIND a `string` field collects — a platform keyword (see {@link
+   * FormInputMode}). The renderer draws the matching keyboard or native control:
+   * `numeric`/`decimal` a text box with that keyboard hint (the value stays the
+   * typed string, so `"007"` keeps its leading zeros), `tel`/`email`/`url` the
+   * matching native control, `text` or absent a plain text box. It DRAWS, it does
+   * not validate — the answer door still enforces `type`, `pattern` and `format`.
+   * When present it OUTRANKS `format` for the control. A value outside the set is
+   * read as absent (the server ask door is the authority that refuses it).
+   */
+  readonly inputMode?: FormInputMode;
+  /**
+   * The CONTROL to draw for this property in place of its shape's default — a
+   * platform keyword (see {@link FormControl}). `chips` draws a `string`-with-`enum`
+   * or an `array` of such strings as a chip grid; `textarea` draws a `string` as a
+   * multi-line text control. It DRAWS, it does not validate — the answer door still
+   * enforces the property's `type`, `enum`, `maxLength` and the rest. A value outside
+   * the set is read as absent (the server ask door is the authority that refuses it).
+   */
+  readonly control?: FormControl;
   /**
    * Platform date-constraint keys on a `string`/`date` (or `date-time`) property. They
    * are NOT the JSON-Schema numeric keywords (which are inert on a string): `minDate`/

package/src/state-binding/README.md

@@ -9,12 +9,14 @@ it; holds no edge to jq (the jq fields render through the host's ambient
 
 - **template `input` jq** — input is the record (`.`), declared params bound as
   `$params`; returns the injected value.
-- **custom injection jq** — over `{ record, input }`; returns the value placed at `into`.
-- **adapter** — over `{ output, input }`; CONSTRUCTS the update jq's declared input
-  object.
-- **template `update` jq** — over `{ record, input }` where `input` is the adapter's
-  output; returns a template-relative op batch.
-- **custom `update` jq** — over `{ record, output, input }`; returns `[{op, path, value}]`.
+- **custom injection jq** — over the record (`.`), the run input bound as `$input`; returns
+  the value placed at `into`.
+- **adapter** — over the tool output (`.`), the run input bound as `$input`; CONSTRUCTS the
+  update jq's declared input object.
+- **template `update` jq** — over the record subtree (`.`), the adapter's output bound as
+  `$input`; returns a template-relative op batch.
+- **custom `update` jq** — over the tool output (`.`), the run input bound as `$input` and the
+  record as `$record`; returns `[{op, path, value}]`.
 - **`subject_expr`** — a jq yielding the record KEY: a bare key string, or a full subject object.
 - **`scope_expr`** — optional; a boolean jq predicate. When it is false, the state is skipped for the run.
 
@@ -28,7 +30,8 @@ canonical, parseable object so a stored adapter reopens as the form it was autho
 ```
 
 - `<key>` — a bare identifier, or a JSON string when it is not one.
-- `<value>` — one of: a field path (`.output…` / `.input…`), a JSON literal, or a raw
+- `<value>` — one of: a field path (an output field `.…`, the whole output `.`, an input
+  field `$input…`), a JSON literal, or a raw
   jq expression, each wrapped in `(…)`.
 
 `parseAdapter` inverts it: `parseAdapter(compileAdapter(rows).jq) === rows` for every

package/src/state-binding/UpdateRow.tsx

@@ -1,8 +1,8 @@
 /**
  * The update list of one attached state. Each update applies AFTER the run: either
  * a template `update` jq (picked by name, whose declared input is authored through
- * the adapter mapping) or a custom jq over `{ record, output, input }` that authors
- * the whole op batch itself. An optional op-id expression carries idempotency.
+ * the adapter mapping) or a custom jq over the tool output (its `.`, with the run input
+ * bound as `$input` and the record as `$record`) that authors the whole op batch itself. An optional op-id expression carries idempotency.
  */
 import type { ReactNode } from 'react';
 
@@ -114,7 +114,7 @@ function UpdateRowEditor({
         <BindingTemplatedJqField
           label={`Custom update jq ${String(index + 1)}`}
           required
-          description="A jq over `{ record, output, input }` returning a template-relative op batch."
+          description="A jq over the tool output (`.`), with `$input` and `$record` bound, returning a template-relative op batch."
           value={update.jq}
           onChange={(next) => {
             onChange({

package/src/state-binding/adapter.ts

@@ -3,9 +3,9 @@
  *
  * A named template `update` jq declares an input object (its `params` / declared
  * input keys). A binding must map the run's OUTPUT (and the run's INPUT) into that
- * object; that mapping is the `adapter` — a single jq program over `{ output, input }`
- * that CONSTRUCTS the update jq's declared input (which the update jq then reads as
- * `.input` alongside the record).
+ * object; that mapping is the `adapter` — a single jq program over the tool output
+ * (its `.`) with the run input bound as `$input`, that CONSTRUCTS the update jq's
+ * declared input (which the update jq then reads as `$input`, over the record).
  *
  * The editor authors the adapter as a ROW form: one row per declared input key,
  * each row picking one of three value sources — a picked field (from the run's
@@ -17,10 +17,10 @@
  * object.
  */
 
-/** Which root of `{ output, input }` a picked field reads. */
+/** Which value a picked field reads: the tool output (the program's `.`) or the run input (`$input`). */
 export type FieldRoot = 'output' | 'input';
 
-/** A picked field: a path into `output` or `input`. */
+/** A picked field: a path into the tool output or the run input. */
 export interface FieldSource {
   readonly kind: 'field';
   readonly root: FieldRoot;
@@ -33,7 +33,7 @@ export interface LiteralSource {
   readonly json: string;
 }
 
-/** A raw jq expression over `{ output, input }`. */
+/** A raw jq expression over the tool output (its `.`), with the run input bound as `$input`. */
 export interface JqSource {
   readonly kind: 'jq';
   readonly expr: string;
@@ -59,13 +59,19 @@ export function jqKey(key: string): string {
   return IDENTIFIER.test(key) ? key : JSON.stringify(key);
 }
 
-/** A picked field rendered as a jq path, e.g. `.output.user.name` / `.input["odd key"]`. */
+/**
+ * A picked field rendered as a jq path: an output field reads off the program root
+ * (`.user.name`, `.["odd key"]`, the whole output `.`), an input field off the bound run
+ * input (`$input.user.name`, the whole input `$input`).
+ */
 export function fieldPathToJq(root: FieldRoot, path: readonly string[]): string {
-  let out = `.${root}`;
+  let out = root === 'input' ? '$input' : '';
   for (const segment of path) {
-    out += IDENTIFIER.test(segment) ? `.${segment}` : `[${JSON.stringify(segment)}]`;
+    out += IDENTIFIER.test(segment)
+      ? `.${segment}`
+      : `${out === '' ? '.' : ''}[${JSON.stringify(segment)}]`;
   }
-  return out;
+  return out === '' ? '.' : out;
 }
 
 /** The jq fragment ONE row's value compiles to — the row's "show jq". */
@@ -95,7 +101,7 @@ export function rowValueJq(source: MappingSource): AdapterCompileResult {
 
 /**
  * Compile a mapping form into ONE adapter jq that constructs the update jq's
- * declared input over `{ output, input }`. An empty form compiles to the
+ * declared input over the tool output and `$input`. An empty form compiles to the
  * empty object `{}`; a blank target, a duplicate target, or an invalid source is a
  * loud error.
  */
@@ -128,7 +134,7 @@ export function defaultRowsForInput(params: readonly string[]): MappingRow[] {
 // `compileAdapter` emits a canonical, PARSEABLE shape so a stored adapter reopens as
 // the form it was authored in (never UI-only state): the object
 // `{ <key>: (<value>), … }` where `<key>` is a bare identifier or a JSON string and
-// `<value>` is one of — a field path `.output…` / `.input…`, a JSON literal, or a raw
+// `<value>` is one of — a field path `.…` (output) / `$input…` (input), a JSON literal, or a raw
 // jq expression. `parseAdapter` inverts it; `parse(compileAdapter(rows).jq) === rows`
 // for every row kind whose literal is already canonical JSON. A shape it does not
 // recognise returns `null` — the editor falls back to the raw-jq escape hatch.
@@ -139,10 +145,19 @@ const ADAPTER_KEY = /^("(?:[^"\\]|\\.)*"|[A-Za-z_][A-Za-z0-9_]*)\s*:\s*\(/;
 
 /** Recover a field source from a pure path expression, or `null` if it is not one. */
 export function parseFieldPath(value: string): FieldSource | null {
-  const head = /^\.(output|input)/.exec(value);
-  if (head === null) return null;
-  const root = head[1] as FieldRoot;
-  let rest = value.slice(head[0].length);
+  let root: FieldRoot;
+  let rest: string;
+  if (value === '.') return { kind: 'field', root: 'output', path: [] };
+  if (value.startsWith('$input')) {
+    root = 'input';
+    rest = value.slice('$input'.length);
+  } else if (value.startsWith('.')) {
+    root = 'output';
+    // A root bracket (`.["odd key"]`) drops its leading dot; a root key keeps it (`.a`).
+    rest = value.startsWith('.[') ? value.slice(1) : value;
+  } else {
+    return null;
+  }
   const path: string[] = [];
   while (rest.length > 0) {
     if (rest.startsWith('.')) {