@salsita-ai/sdk 0.50.0-develop.f101f4c3c9 → 0.50.0-develop.f354d3576d

package/dist/domain/spec/runtime-spec/runtime-spec.d.ts

@@ -0,0 +1,174 @@
+import type { AdminPages, AdminStates, ConfiguratorStates } from '../application/index.js';
+import type { Components } from '../components/index.js';
+import type { Expressions } from '../expressions/index.js';
+import type { Invariants } from '../invariants/index.js';
+import type { JsonSchema } from '../json-schema.js';
+import type { CommonTypes, Defaults, EntityOrAliasName, EntityTypeName, EntityTypes, ModelVersionKey, Presets, SpecAliases } from '../model/index.js';
+import type { Acl, Actions, AppMetadata, AssistantResolvedManifest, Chunks, ParsedDataSpecEntries, ResourceEntry, SpecResourcesConfig, SpecTransformers, Theme, Ui } from '../sections/index.js';
+/**
+ * The part of a parsed entity schema the runtime reads: the entity type and the schema of its
+ * shape, from which it builds the entity's reflection. The full schema with `id` and `type` is
+ * only registered with a deployment, and the compiled shape validators only check presets and
+ * defaults while parsing.
+ */
+export interface RuntimeEntitySchema {
+    readonly entityType: EntityTypeName;
+    readonly shapeSchema: JsonSchema;
+}
+/**
+ * The part of a parsed model version the runtime reads: the entity types, the aliases, the common
+ * types and the schema of every entity's shape. The shapes and the resolved shapes only serve the
+ * parser and the type generator, except the runtime schemas of the latest version's shapes (see
+ * `RuntimeLatestModelVersion`).
+ */
+export interface RuntimeModelVersion {
+    readonly versionKey: ModelVersionKey;
+    readonly entityTypes: EntityTypes;
+    /** Entity types allowed as preset root — members of the RootEntity alias, or all entity types if no RootEntity alias. */
+    readonly rootEntityTypes: readonly EntityTypeName[];
+    readonly aliases: SpecAliases;
+    readonly commonTypes: CommonTypes;
+    readonly entitySchemas: readonly RuntimeEntitySchema[];
+}
+/**
+ * The latest model version of a domain as the runtime reads it: a model version plus the runtime
+ * schema of every shape, which `phx.domain.model` reflects as `<Name>Shape`.
+ */
+export interface RuntimeLatestModelVersion extends RuntimeModelVersion {
+    readonly shapes: ReadonlyMap<EntityOrAliasName, RuntimeShapeSchema>;
+}
+/** The part of a parsed shape the runtime reads: its name and its runtime JSON schema. */
+export interface RuntimeShapeSchema {
+    readonly name: EntityOrAliasName;
+    readonly runtimeSchema: JsonSchema;
+}
+/**
+ * One model version of a domain as the runtime reads it, with the migration file that leads to it.
+ * `version` is the integer version number (1, 2, 3, …), `key` is always `v{N}`, never `latest`,
+ * `isLatest` marks the version of the `latest` model key, and `migrationFile` is the path of the
+ * migration file, present from v2 on.
+ */
+export interface RuntimeResolvedModelVersion {
+    readonly version: number;
+    readonly key: string;
+    readonly isLatest: boolean;
+    readonly modelVersion: RuntimeModelVersion;
+    readonly migrationFile: string | undefined;
+}
+/**
+ * Every model version of a domain as the runtime reads it; it builds the domain's migrations from
+ * them. `latestVersion` is the integer of the `latest` key, and `versionedModels` is sorted
+ * ascending by version number.
+ */
+export interface RuntimeResolvedVersions {
+    readonly latestVersion: number;
+    readonly versionedModels: readonly RuntimeResolvedModelVersion[];
+}
+/** The model of a domain as the runtime reads it: the latest version and every earlier one. */
+interface RuntimeDomainModel {
+    readonly latestModel: RuntimeLatestModelVersion;
+    readonly resolvedVersions: RuntimeResolvedVersions;
+}
+/** The part of a parsed data schema the runtime reads: the JSON schema it validates the data with. */
+export interface RuntimeDataSchemaEntry {
+    readonly runtimeSchema: JsonSchema;
+}
+/**
+ * The data schemas as the runtime reads them: the JSON schema of each kind of data and the hash of
+ * the published data. The enhanced schemas, with Phoenix references, only serve the type generator.
+ */
+export interface RuntimeDataSchemas {
+    readonly publishedData: RuntimeDataSchemaEntry;
+    readonly publishedDataHash: string;
+    readonly sessionData: RuntimeDataSchemaEntry;
+    readonly frontendData: RuntimeDataSchemaEntry;
+    readonly backendData: RuntimeDataSchemaEntry | undefined;
+    readonly finalizeData: RuntimeDataSchemaEntry;
+    readonly prefetchedFinalizeData: RuntimeDataSchemaEntry;
+    readonly finalizeResult: RuntimeDataSchemaEntry;
+    readonly callbackData: RuntimeDataSchemaEntry;
+}
+/**
+ * The assistant as the runtime reads it: its resolved manifest. The parsed assistant schema the
+ * manifest is resolved from only serves the parser.
+ */
+export type RuntimeAssistantSpec = {
+    readonly resolved: AssistantResolvedManifest;
+} | null;
+/**
+ * The data spec as the runtime reads it: the data entries and their chunks. The data entries and
+ * admin data pages the parser derives from them only serve the admin spec and the type generator.
+ */
+export interface RuntimeDataSpec {
+    /** Validated entries grouped by their source `$data` subsection for generated SDK config. */
+    readonly entries: ParsedDataSpecEntries;
+    /** Validated published-data chunks, including the auto-injected `system` chunk when needed. */
+    readonly chunks: Chunks;
+}
+/**
+ * The configurator part of the runtime spec. It leaves out the configuration schema and its
+ * version, which only a deployment registers, and the assistant's server settings (instructions
+ * and AI settings), which must never reach the browser of a customer.
+ */
+export interface RuntimeConfiguratorSpec extends RuntimeDomainModel {
+    readonly components: Components;
+    readonly presets: Presets;
+    readonly expressions: Expressions;
+    readonly actions: Actions;
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly states: ConfiguratorStates;
+    readonly theme: Theme;
+    readonly ui: Ui;
+    readonly transformers: SpecTransformers;
+    readonly dataSchemas: RuntimeDataSchemas;
+    readonly assistant: RuntimeAssistantSpec;
+}
+/**
+ * The admin part of the runtime spec. It leaves out the configuration schema and its version, which
+ * only a deployment registers.
+ */
+export interface RuntimeAdminSpec extends RuntimeDomainModel {
+    readonly components: Components;
+    readonly presets: Presets;
+    readonly expressions: Expressions;
+    readonly invariants: Invariants;
+    readonly defaults: Defaults;
+    readonly states: AdminStates;
+    readonly adminPages: AdminPages;
+}
+/**
+ * The infrastructure settings the runtime reads: access control and resources. The environment
+ * variable declarations only drive the generated environment readers.
+ */
+export interface RuntimeInfra {
+    readonly acl: Acl;
+    readonly resources: readonly ResourceEntry[] | undefined;
+    readonly resourcesConfig: SpecResourcesConfig | undefined;
+}
+/**
+ * The parsed application spec as the runtime reads it: what `ApplicationRuntime` builds the
+ * configurator and admin runtimes from, and the sections an application needs besides its domains
+ * (data spec, app metadata, resources, access control, user interface settings, webhook data
+ * schemas, admin pages). `phoenix sync` and `phoenix build` write it to
+ * `.phoenix/application-spec.json` with `encodeRuntimeSpec`.
+ *
+ * Its sections are the spec data types of `domain`, the types the parser produces, so a parsed
+ * `ApplicationSpec` is assignable to it. It leaves out what only the parser, the type generator or
+ * a deployment use, and holds plain data, Maps and Sets only, so it can be encoded as JSON.
+ */
+export interface RuntimeSpec {
+    readonly appMetadata: AppMetadata;
+    readonly dataSpec: RuntimeDataSpec;
+    readonly configurator: RuntimeConfiguratorSpec;
+    readonly admin: RuntimeAdminSpec;
+    readonly infra: RuntimeInfra;
+}
+/**
+ * Takes from a parsed application spec the part the runtime reads. It reuses the sections it keeps
+ * whole, and builds trimmed copies of the model versions, data schemas, assistant and data spec
+ * without what the runtime does not read. It takes any `RuntimeSpec`, which a parsed
+ * `ApplicationSpec` is, and copies only what the type declares.
+ */
+export declare const toRuntimeSpec: (spec: RuntimeSpec) => RuntimeSpec;
+export {};

package/dist/domain/spec/runtime-spec/runtime-spec.js

@@ -0,0 +1 @@
+let e=e=>({versionKey:e.versionKey,entityTypes:e.entityTypes,rootEntityTypes:e.rootEntityTypes,aliases:e.aliases,commonTypes:e.commonTypes,entitySchemas:e.entitySchemas.map(e=>({entityType:e.entityType,shapeSchema:e.shapeSchema}))}),s=e=>({runtimeSchema:e.runtimeSchema}),a=s=>{let a;return{latestModel:{...e(a=s.latestModel),shapes:new Map([...a.shapes].map(([e,s])=>[e,{name:s.name,runtimeSchema:s.runtimeSchema}]))},resolvedVersions:{latestVersion:s.resolvedVersions.latestVersion,versionedModels:s.resolvedVersions.versionedModels.map(s=>({version:s.version,key:s.key,isLatest:s.isLatest,migrationFile:s.migrationFile,modelVersion:e(s.modelVersion)}))}}};export const toRuntimeSpec=e=>{let t,{configurator:n,admin:i,infra:r}=e;return{configurator:{components:n.components,presets:n.presets,expressions:n.expressions,actions:n.actions,invariants:n.invariants,dataSchemas:{publishedDataHash:(t=n.dataSchemas).publishedDataHash,publishedData:s(t.publishedData),sessionData:s(t.sessionData),frontendData:s(t.frontendData),backendData:t.backendData&&s(t.backendData),finalizeData:s(t.finalizeData),prefetchedFinalizeData:s(t.prefetchedFinalizeData),finalizeResult:s(t.finalizeResult),callbackData:s(t.callbackData)},defaults:n.defaults,states:n.states,theme:n.theme,ui:n.ui,transformers:n.transformers,assistant:n.assistant&&{resolved:n.assistant.resolved},...a(n)},admin:{components:i.components,presets:i.presets,expressions:i.expressions,invariants:i.invariants,defaults:i.defaults,states:i.states,adminPages:i.adminPages,...a(i)},appMetadata:e.appMetadata,infra:{acl:r.acl,resources:r.resources,resourcesConfig:r.resourcesConfig},dataSpec:{entries:e.dataSpec.entries,chunks:e.dataSpec.chunks}}};

package/dist/{application-spec/generate-application → domain/spec}/runtime-spec/spec-code-id.d.ts

@@ -1,4 +1,4 @@
-import type { MemoEvalPlan } from '../../parse-application-files/index.js';
+import type { MemoEvalPlan } from '../expressions/index.js';
 /**
  * The id under which the generated `.phoenix/spec-code.ts` holds one piece of code written in YAML,
  * and under which the runtime looks it up. Ids are unique within one domain; the configurator and

package/dist/domain/spec/sections/actions.d.ts

@@ -0,0 +1,23 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { EnhancedJsonSchemaType } from '../../core/index.js';
+import type { JsonSchema } from '../json-schema.js';
+import type { ActionName } from '../model/index.js';
+/** One parameter of an action: its declared schema, and whether a call has to pass it (a nullable param is optional). */
+export interface ActionParam {
+    readonly schema: EnhancedJsonSchemaType;
+    readonly required: boolean;
+}
+/**
+ * One validated action declaration. `params` and `result` keep the enhanced schemas for codegen and
+ * for consumers that expose the action; `paramsSchema` is the AJV-ready object schema of the parameters, with the
+ * refs resolved into `$defs`, which the action system validates the arguments of a call against.
+ */
+export type Action = Branded<'Action', {
+    readonly name: ActionName;
+    readonly description?: string;
+    readonly params: Readonly<Record<string, ActionParam>>;
+    readonly result: Readonly<Record<string, EnhancedJsonSchemaType>>;
+    readonly paramsSchema: JsonSchema;
+}>;
+/** The validated `actions` section: every declared action by name, in declaration order; empty when the spec declares none. */
+export type Actions = Branded<'Actions', ReadonlyMap<ActionName, Action>>;

package/dist/domain/spec/sections/actions.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/app-metadata.d.ts

@@ -0,0 +1,18 @@
+import type { Branded } from '@salsita-ai/common/utils';
+import type { ApplicationVersion } from './application-version.js';
+/**
+ * Validated application metadata — version, auth, infrastructure settings.
+ * Used by codegen for ApplicationVersion export and builder chain methods.
+ */
+export type AppMetadata = Branded<'AppMetadata', {
+    readonly applicationVersion: ApplicationVersion;
+    readonly workspace: boolean;
+    readonly webComponentTag: string | undefined;
+    readonly pageTitle: string | undefined;
+    readonly useAuthHook: boolean;
+    readonly useClerk: boolean;
+    readonly enableAdminRelease: boolean;
+    readonly jsonSchemaValidator: 'ajv' | 'csp-compatible';
+    readonly gltfDecoder: 'js' | 'wasm';
+    readonly collectFinalizeData: boolean;
+}>;

package/dist/domain/spec/sections/app-metadata.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/application-version.d.ts

@@ -0,0 +1,7 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Branded semantic version (x.y.z) of the application.
+ * Exported by codegen as the `ApplicationVersion` constant and stored as
+ * `applicationVersion` on the deployment record.
+ */
+export type ApplicationVersion = Branded<'ApplicationVersion', string>;

package/dist/domain/spec/sections/application-version.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/{application → spec/sections}/assistant/assistant-manifest.d.ts

@@ -1,3 +1,4 @@
+import type { AssistantFormElementDescriptor } from './form/index.js';
 /**
  * Where one exposed assistant GraphQL field reads its value on the `$` entity: a stored field name,
  * or an expression name including its `$`. `localized` marks a localizable value that resolves to a
@@ -7,18 +8,28 @@ export interface AssistantFieldSource {
     readonly source: string;
     readonly localized?: true;
 }
+/**
+ * What the integrator promises about a list of choices, so the agent can read it once and reuse it:
+ * `sameForAllInstances` when every entity of the type gets the same list, `constantDuringSession`
+ * when the list does not change during a session. A hint only adds a sentence to the description of
+ * the recipe group or options edge it is declared on; nothing verifies it.
+ */
+export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
+export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
 /**
  * One recipe group the assistant manifest exposes on an entity type: a `childEntityRecipes` instance
  * under `childRecipes`, a `replaceEntityRecipes` instance under `replaceRecipes`. `groupId` is the
- * name the agent addresses the group by, `instanceName` the component instance it reads,
- * `description` the manifest's text replacing the component's group description, and `dryRuns`
- * whether the recipes of the group can be dry-run.
+ * name of its field on `<Type>ChildRecipes` or `<Type>ReplaceRecipes` and the id the agent passes to
+ * `addChild` or `replaceEntity`, `instanceName` the component instance it reads, `description` the
+ * manifest's text for that field, `dryRuns` whether the recipes of the group can be dry-run, and
+ * `hints` the sentences of the field's description saying when the agent can reuse what it read.
  */
 export interface AssistantRecipeGroup {
     readonly groupId: string;
     readonly instanceName: string;
     readonly description?: string;
     readonly dryRuns: boolean;
+    readonly hints: readonly AssistantResolvedHint[];
 }
 /**
  * The options edge of one writable field the assistant manifest links to its component. `field` is
@@ -35,6 +46,16 @@ export interface AssistantFieldOptions {
     readonly validate: boolean;
     readonly dryRuns: boolean;
 }
+/**
+ * One view the assistant manifest lets the agent take a screenshot of an entity from: `view` is the
+ * value of the `<Type>ScreenshotView` enum the agent asks for it by, `instanceName` the
+ * `agentScreenshot` component instance that renders it, and `description` what the view shows.
+ */
+export interface AssistantScreenshotView {
+    readonly view: string;
+    readonly instanceName: string;
+    readonly description: string;
+}
 /**
  * Experimental assistant manifest generated from the application spec `assistant` section. `sdl` is
  * the GraphQL schema text rebuilt from the resolved manifest; `fields` maps each GraphQL object type's exposed
@@ -46,7 +67,8 @@ export interface AssistantFieldOptions {
  * the recipe groups `meta { childRecipes }` and `addChild` expose, in manifest order, and absent
  * means none; `replaceRecipes` lists the same for `meta { replaceRecipes }` and `replaceEntity`;
  * `fieldOptions` lists, per entity type, the options edges `meta` exposes for its
- * writable fields, and absent means none; `actions` maps each custom `Mutation` field to the
+ * writable fields, and absent means none; `screenshots` lists, per entity type, the views
+ * `meta { screenshot }` renders, and absent means none; `actions` maps each custom `Mutation` field to the
  * declared action it runs, and absent means none; `lenses` holds the generated lens fragments, and
  * absent means none: `declarations` is the text the prompt shows, each lens once with its relations
  * spreading the lens itself, and `definitions` the valid GraphQL injected into an operation that
@@ -63,9 +85,12 @@ export interface AssistantManifest {
     readonly childRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly replaceRecipes?: Readonly<Record<string, readonly AssistantRecipeGroup[]>>;
     readonly fieldOptions?: Readonly<Record<string, readonly AssistantFieldOptions[]>>;
+    readonly screenshots?: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actions?: Readonly<Record<string, string>>;
     readonly lenses?: {
         readonly declarations: string;
         readonly definitions: string;
     };
+    /** The project's own form elements, in YAML order; absent means none. */
+    readonly formElements?: readonly AssistantFormElementDescriptor[];
 }

package/dist/domain/{application → spec/sections}/assistant/assistant-resolved-manifest.d.ts

@@ -1,4 +1,5 @@
-import type { AssistantFieldOptions, AssistantRecipeGroup } from './assistant-manifest.js';
+import type { AssistantFieldOptions, AssistantRecipeGroup, AssistantResolvedHint, AssistantScreenshotView } from './assistant-manifest.js';
+import type { AssistantFormElementDescriptor } from './form/index.js';
 /** JSON description of a scalar or recursively nested list, including nullability at each level. */
 export type AssistantValueType = {
     readonly kind: 'scalar';
@@ -50,12 +51,18 @@ export interface AssistantResolvedManifest {
     readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly optionsEdges: Readonly<Record<string, readonly AssistantResolvedOptionsEdge[]>>;
+    /** The screenshot views of each entity type with at least one, aliases expanded, in manifest order. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
     readonly actionFields: readonly AssistantResolvedAction[];
+    /** The entity types that declare invariants, whose `meta` lists the warnings and notices they hold. */
+    readonly invariantTypes: readonly string[];
     /** The declared lenses by name: when to use each, and how many levels its tagged relations nest. */
     readonly lenses: Readonly<Record<string, {
         readonly description: string;
         readonly maxDepth: number;
     }>>;
+    /** The project's own form elements, in YAML order, which the prompt lists after the built-ins and the panel renders with their registered components. */
+    readonly formElements: readonly AssistantFormElementDescriptor[];
 }
 /** Optional mutation input for one stored field, using its exposed name. */
 export interface AssistantWritableField {
@@ -69,14 +76,8 @@ export interface AssistantWritableType {
     readonly entityType: string;
     readonly fields: readonly AssistantWritableField[];
 }
-/** Description hints resolved from recipe/option entries; no parse context is retained. */
-export declare const ASSISTANT_HINTS: readonly ['sameForAllInstances', 'constantDuringSession'];
-export type AssistantResolvedHint = (typeof ASSISTANT_HINTS)[number];
-/** Recipe groups and their description hints for one entity type. */
-export interface AssistantResolvedRecipes {
-    readonly groups: readonly AssistantRecipeGroup[];
-    readonly hints: readonly AssistantResolvedHint[];
-}
+/** The recipe groups of one kind on one entity type or alias key, in manifest order, each with its own hints. */
+export type AssistantResolvedRecipes = readonly AssistantRecipeGroup[];
 /** One options edge, carrying the write-validation contract and schema description hints. */
 export interface AssistantResolvedOptionsEdge {
     readonly options: AssistantFieldOptions;
@@ -113,6 +114,8 @@ export interface AssistantDeclarations {
     readonly writable: Readonly<Record<string, Readonly<Record<string, AssistantDeclaredWrite>>>>;
     readonly childRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
     readonly replaceRecipes: Readonly<Record<string, AssistantResolvedRecipes>>;
+    /** The screenshot views under the entity type or alias key that declares them. */
+    readonly screenshots: Readonly<Record<string, readonly AssistantScreenshotView[]>>;
 }
 /** An original field declaration, including metadata needed to reapply inheritance and enum descriptions. */
 export interface AssistantDeclaredField extends AssistantResolvedField {

package/dist/domain/spec/sections/assistant/assistant-resolved-manifest.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/assistant/form/assistant-form-element-name.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The shape of a form element's tag, and of its attributes' names: the panel reads form markup
+ * with lowercase tag and attribute names, so a name with an upper-case letter would never match.
+ */
+export declare const ASSISTANT_FORM_NAME_PATTERN: RegExp;
+/**
+ * Whether a tag is an HTML element name, which no form element may take, so that markup in a form
+ * is never mistaken for HTML. The spec rejects a project's element by it and the panel's registry
+ * refuses one, so both read the same list.
+ */
+export declare const isHtmlElementName: (name: string) => boolean;

package/dist/domain/spec/sections/assistant/form/assistant-form-element-name.js

@@ -0,0 +1,8 @@
+let e=new Set(`a abbr acronym address applet area article aside audio b base basefont bdi bdo big blink blockquote body br
+  button canvas caption center cite code col colgroup data datalist dd del details dfn dialog dir div dl dt em
+  embed fieldset figcaption figure font footer form frame frameset h1 h2 h3 h4 h5 h6 head header hgroup hr html
+  i iframe image img input ins kbd keygen label legend li link main map mark marquee math menu menuitem meta
+  meter nav nobr noembed noframes noscript object ol optgroup option output p param picture plaintext pre
+  progress q rb rp rt rtc ruby s samp script search section select slot small source span strike strong style
+  sub summary sup svg table tbody td template textarea tfoot th thead time title tr track tt u ul var video wbr
+  xmp`.split(/\s+/));export const ASSISTANT_FORM_NAME_PATTERN=/^[a-z][a-z0-9-]*$/;export const isHtmlElementName=t=>e.has(t);

package/dist/domain/{application → spec/sections}/assistant/form/assistant-form-elements.d.ts

@@ -7,14 +7,22 @@ export type AssistantFormRole = 'group' | 'choice' | 'choices' | 'option' | 'inp
 /** The type an attribute of a form element is validated and coerced to; the model writes every attribute as a string. */
 export interface AssistantFormAttribute {
     readonly type: 'string' | 'number' | 'integer' | 'boolean';
-    readonly enum?: readonly string[];
+    /** The words a string, or the numbers a number, may be; a number's are written as text in the markup. */
+    readonly enum?: readonly (string | number)[];
     /** A JSON Schema `pattern` a string attribute must match, such as a resource path or a `#rrggbb` color. */
     readonly pattern?: string;
+    /** The bounds a number attribute must be within, as in JSON Schema. */
+    readonly minimum?: number;
+    readonly maximum?: number;
+    /** The bounds of a string attribute's length, as in JSON Schema. */
+    readonly minLength?: number;
+    readonly maxLength?: number;
 }
 /**
  * An element the assistant can write inside a ```` ```form ```` fence of its reply to ask the user
  * something. The panel renders it, and the SDK prompt lists it, so the model and the panel agree on
- * one set of elements.
+ * one set of elements: the built-ins below, followed by the project's own, which its YAML declares
+ * under `assistant.formElements` with the fields up to `required`.
  */
 export interface AssistantFormElementDescriptor {
     /** The tag: lowercase, and never the name of an HTML element. */
@@ -22,23 +30,21 @@ export interface AssistantFormElementDescriptor {
     readonly role: AssistantFormRole;
     /** What the element is for, printed in the prompt after its signature. */
     readonly description: string;
-    /** Attributes beyond the built-in `label` and, on an option or an input, `value`. */
-    readonly attributes: Readonly<Record<string, AssistantFormAttribute>>;
-    readonly required?: readonly string[];
     /**
-     * The type the built-in `value` of an option or an input is validated and coerced to: a string
-     * by default, or `none` for an element that takes no `value`.
+     * Attributes beyond the built-in `label`, in the order the prompt lists them. An option or an
+     * input that takes a `value` declares it like any other: by convention an option answers with
+     * it instead of its label, and an input starts with it.
      */
-    readonly valueType?: 'number' | 'none';
+    readonly attributes: Readonly<Record<string, AssistantFormAttribute>>;
+    readonly required?: readonly string[];
     /**
      * An input the user answers with one action, such as a `confirm`: a form whose only question it
      * is sends on that action, without a submit button, as a lone `choice` sends on the first pick.
      */
     readonly quick?: true;
     /**
-     * The attributes an option sends, tried in order, when it has neither `value` nor `label`. An
-     * option that declares them and has none of them, nor `value` or `label`, makes its form fail;
-     * its component shows its `value` as its name when it has no `label`.
+     * The attributes an option can answer with besides `label`, in the order its component tries
+     * them. An option that declares them and has none of them, nor `label`, makes its form fail.
      */
     readonly identity?: readonly string[];
 }
@@ -49,21 +55,12 @@ export type AssistantFormAttributeValue<ATTRIBUTE extends AssistantFormAttribute
 type RequiredAttributeName<DESCRIPTOR> = DESCRIPTOR extends {
     readonly required: readonly (infer NAME)[];
 } ? NAME : never;
-type StartingValueAttribute<DESCRIPTOR extends AssistantFormElementDescriptor> = DESCRIPTOR extends {
-    readonly role: 'input';
-} ? DESCRIPTOR extends {
-    readonly valueType: 'none';
-} ? Record<never, never> : {
-    readonly value?: DESCRIPTOR extends {
-        readonly valueType: 'number';
-    } ? number : string;
-} : Record<never, never>;
 /**
  * The attributes a form element's component gets, typed from its descriptor: the declared ones,
- * optional unless `required`, and an input's starting `value`. The form validates the markup
- * against the same descriptor, so the component can rely on these types.
+ * optional unless `required`. The form validates the markup against the same descriptor, so the
+ * component can rely on these types.
  */
-export type AssistantFormElementAttributes<DESCRIPTOR extends AssistantFormElementDescriptor> = StartingValueAttribute<DESCRIPTOR> & {
+export type AssistantFormElementAttributes<DESCRIPTOR extends AssistantFormElementDescriptor> = {
     readonly [NAME in keyof DESCRIPTOR['attributes'] as NAME extends RequiredAttributeName<DESCRIPTOR> ? NAME : never]: AssistantFormAttributeValue<DESCRIPTOR['attributes'][NAME]>;
 } & {
     readonly [NAME in keyof DESCRIPTOR['attributes'] as NAME extends RequiredAttributeName<DESCRIPTOR> ? never : NAME]?: AssistantFormAttributeValue<DESCRIPTOR['attributes'][NAME]>;
@@ -88,12 +85,19 @@ export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
     readonly name: 'reply';
     readonly role: 'option';
     readonly description: 'A short answer shown as a button.';
-    readonly attributes: {};
+    readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
+    };
 }, {
     readonly name: 'card';
     readonly role: 'option';
     readonly description: 'A tile with an optional picture over its label and a one-line `description`. `image` is a path you read on an `imageUrl` field. Without `value` or `label` it sends its `description`, or else its `image`.';
     readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
         readonly description: {
             readonly type: 'string';
         };
@@ -102,12 +106,15 @@ export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
             readonly pattern: string;
         };
     };
-    readonly identity: readonly ["description", "image"];
+    readonly identity: readonly ["value", "description", "image"];
 }, {
     readonly name: 'swatch';
     readonly role: 'option';
     readonly description: 'A small tile of a color or a material, without text: its label shows on hover. `color` is `#rrggbb`, as on the `color` field of an option, and `image` a path you read on an `imageUrl` field. Without `value` or `label` it sends its `color`, or else its `image`.';
     readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
         readonly color: {
             readonly type: 'string';
             readonly pattern: '^#[0-9a-fA-F]{6}$';
@@ -117,12 +124,15 @@ export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
             readonly pattern: string;
         };
     };
-    readonly identity: readonly ["color", "image"];
+    readonly identity: readonly ["value", "color", "image"];
 }, {
     readonly name: 'text';
     readonly role: 'input';
     readonly description: 'A single line the user types.';
     readonly attributes: {
+        readonly value: {
+            readonly type: 'string';
+        };
         readonly placeholder: {
             readonly type: 'string';
         };
@@ -132,6 +142,9 @@ export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
     readonly role: 'input';
     readonly description: 'A number the user types, with a slider when both `min` and `max` are given. The answer carries the `unit`, as in `Length: 240 cm`.';
     readonly attributes: {
+        readonly value: {
+            readonly type: 'number';
+        };
         readonly min: {
             readonly type: 'number';
         };
@@ -145,13 +158,11 @@ export declare const ASSISTANT_BUILT_IN_FORM_ELEMENTS: readonly [{
             readonly type: 'string';
         };
     };
-    readonly valueType: 'number';
 }, {
     readonly name: 'confirm';
     readonly role: 'input';
     readonly description: "A yes or no question, shown as two buttons. It answers with the user's own words for yes and no, such as `Yes` or `Ano`, and alone in a form it sends on the click.";
     readonly attributes: {};
-    readonly valueType: 'none';
     readonly quick: true;
 }];
 /** The name of a built-in form element. */

package/dist/domain/spec/sections/assistant/form/assistant-form-elements.js

@@ -0,0 +1 @@
+import{ASSISTANT_RESOURCE_PATH_PATTERN as e}from"./assistant-resource-path.js";export const ASSISTANT_BUILT_IN_FORM_ELEMENTS=[{name:"group",role:"group",description:"Puts related questions together under its label.",attributes:{}},{name:"choice",role:"choice",description:"The user picks exactly one of its options.",attributes:{}},{name:"choices",role:"choices",description:"The user picks any number of its options.",attributes:{}},{name:"reply",role:"option",description:"A short answer shown as a button.",attributes:{value:{type:"string"}}},{name:"card",role:"option",description:"A tile with an optional picture over its label and a one-line `description`. `image` is a path you read on an `imageUrl` field. Without `value` or `label` it sends its `description`, or else its `image`.",attributes:{value:{type:"string"},description:{type:"string"},image:{type:"string",pattern:e}},identity:["value","description","image"]},{name:"swatch",role:"option",description:"A small tile of a color or a material, without text: its label shows on hover. `color` is `#rrggbb`, as on the `color` field of an option, and `image` a path you read on an `imageUrl` field. Without `value` or `label` it sends its `color`, or else its `image`.",attributes:{value:{type:"string"},color:{type:"string",pattern:"^#[0-9a-fA-F]{6}$"},image:{type:"string",pattern:e}},identity:["value","color","image"]},{name:"text",role:"input",description:"A single line the user types.",attributes:{value:{type:"string"},placeholder:{type:"string"}}},{name:"number",role:"input",description:"A number the user types, with a slider when both `min` and `max` are given. The answer carries the `unit`, as in `Length: 240 cm`.",attributes:{value:{type:"number"},min:{type:"number"},max:{type:"number"},step:{type:"number"},unit:{type:"string"}}},{name:"confirm",role:"input",description:"A yes or no question, shown as two buttons. It answers with the user's own words for yes and no, such as `Yes` or `Ano`, and alone in a form it sends on the click.",attributes:{},quick:!0}];

package/dist/domain/{application → spec/sections}/assistant/form/index.d.ts

@@ -1,4 +1,4 @@
+export { ASSISTANT_FORM_NAME_PATTERN, isHtmlElementName } from './assistant-form-element-name.js';
 export { ASSISTANT_BUILT_IN_FORM_ELEMENTS } from './assistant-form-elements.js';
 export type { AssistantBuiltInFormElementAttributes, AssistantBuiltInFormElementName, AssistantFormAttribute, AssistantFormAttributeValue, AssistantFormElementAttributes, AssistantFormElementDescriptor, AssistantFormRole, } from './assistant-form-elements.js';
 export { ASSISTANT_RESOURCE_PATH_PATTERN } from './assistant-resource-path.js';
-export { getAssistantFormValueAttribute } from './get-assistant-form-value-attribute.js';

package/dist/domain/spec/sections/assistant/form/index.js

@@ -0,0 +1 @@
+export{ASSISTANT_FORM_NAME_PATTERN,isHtmlElementName}from"./assistant-form-element-name.js";export{ASSISTANT_BUILT_IN_FORM_ELEMENTS}from"./assistant-form-elements.js";export{ASSISTANT_RESOURCE_PATH_PATTERN}from"./assistant-resource-path.js";

package/dist/domain/spec/sections/assistant/index.d.ts

@@ -0,0 +1,4 @@
+export { ASSISTANT_HINTS } from './assistant-manifest.js';
+export type { AssistantResolvedManifest, AssistantDeclaredField, AssistantDeclarations, AssistantDeclaredWrite, AssistantResolvedField, AssistantValueType, AssistantRelationType, AssistantStates, AssistantWritableType, AssistantWritableField, AssistantResolvedRecipes, AssistantResolvedOptionsEdge, AssistantResolvedAction, AssistantResolvedActionResult, } from './assistant-resolved-manifest.js';
+export type { AssistantFieldSource, AssistantResolvedHint, AssistantRecipeGroup, AssistantFieldOptions, AssistantScreenshotView, AssistantManifest, } from './assistant-manifest.js';
+export * from './form/index.js';

package/dist/domain/spec/sections/assistant/index.js

@@ -0,0 +1 @@
+export{ASSISTANT_HINTS}from"./assistant-manifest.js";export*from"./form/index.js";

package/dist/domain/spec/sections/data-spec/chunks.d.ts

@@ -0,0 +1,23 @@
+import type { Branded } from '@salsita-ai/common/utils';
+/**
+ * Validated published-data chunk name.
+ * Chunk names identify top-level partitions in generated `publishedData`. Data
+ * entries point to these names through their `chunk` field, and the parser adds
+ * the reserved `system` chunk when user chunks exist.
+ */
+export type ChunkName = Branded<'ChunkName', string>;
+/**
+ * A named partition of published data with a scope.
+ * `scope` is typically `'project'` (per-project data) or `'public'` (shared).
+ */
+export interface ChunkDefinition {
+    /** Visibility/storage scope used by runtime data publishing for this chunk. */
+    readonly scope: string;
+}
+/**
+ * Validated chunk definitions, keyed by chunk name.
+ * When any user-defined chunks are present, the reserved `system` chunk is
+ * auto-injected with `scope: 'public'` to carry admin presets/recipes schemas.
+ * When the input is empty, no system injection happens (mirrors domain-spec behavior).
+ */
+export type Chunks = Readonly<Record<ChunkName, ChunkDefinition>>;

package/dist/domain/spec/sections/data-spec/chunks.js

@@ -0,0 +1 @@
+export{};

package/dist/domain/spec/sections/data-spec/custom-data-spec-entry.d.ts

@@ -0,0 +1,16 @@
+import type { DataCellValue, DataSchema } from '../../../core/index.js';
+/** Parsed `$data.custom` entry with validated definition and normalized row values. */
+export interface CustomDataSpecEntry {
+    /** Column/property schema for a custom data row, used by admin pages and published-data schemas. */
+    readonly definition: DataSchema;
+    /** Optional published-data chunk that receives this entry as an array property. */
+    readonly chunk?: string;
+    /** Ownership mode deciding whether data is manual, externally connected, or admin-generated. */
+    readonly kind: 'manual' | 'connected' | 'generated';
+    /** Optional human-readable label used by inferred admin pages and connected-data UI. */
+    readonly title?: string;
+    /** Optional icon name used in inferred admin navigation. */
+    readonly icon?: string;
+    /** Default rows normalized to the same column order as `definition`. */
+    readonly values?: ReadonlyArray<readonly DataCellValue[]>;
+}

package/dist/domain/spec/sections/data-spec/custom-data-spec-entry.js

@@ -0,0 +1 @@
+export{};