@widgetic/creator 0.3.72 → 0.3.74

package/dist/stores/websocketStore.js

@@ -173,6 +173,8 @@ function setupSocketListeners(sock) {
             status: data.status ?? null,
             version: data.version,
             artifactUrl: data.artifactUrl,
+            commitTitle: data.commitTitle ?? null,
+            commitSha: data.commitSha ?? null,
             message: data.message,
             error: data.error,
             timestamp: new Date().toISOString()
@@ -186,6 +188,8 @@ function setupSocketListeners(sock) {
             status: 'success',
             version: data.versionPublished,
             artifactUrl: data.artifactUrl,
+            commitTitle: data.commitTitle ?? null,
+            commitSha: data.commitSha ?? null,
             message: data.message,
             error: undefined,
             timestamp: new Date().toISOString()

package/dist/utils/canvasShapeSnapClient.d.ts

@@ -0,0 +1,27 @@
+/**
+ * canvasShapeSnapClient — the Canvas's Jev-backed stroke recognizer.
+ *
+ * When the user draws a shape freehand, the Canvas measures the stroke in code
+ * and decides on its own whenever the measurements are decisive: a drawn
+ * rectangle is a rectangle, with no model and no network. This client covers the
+ * residue — strokes whose measurements leave several shapes standing (a
+ * near-square, an oval that is almost a circle) — by asking the gateway for one
+ * closed-set decision over the measurements and the shapes the geometry allowed.
+ *
+ * The gateway owns the model, the confidence gate, and the rollout mode; this
+ * client only transports and reports. It never throws: a null result means
+ * "leave the stroke exactly as the user drew it", which is what the Canvas does
+ * with no recognizer at all.
+ */
+import type { StrokeRecognitionRequest, StrokeRecognitionResult } from '@widgetic/canvas';
+export interface CanvasShapeSnapReply extends StrokeRecognitionResult {
+    /** `jev` = a real verdict; `degraded`/`disabled`/`no_candidates` = fallback. */
+    source: 'jev' | 'degraded' | 'disabled' | 'no_candidates' | 'client_unavailable';
+}
+export declare function recognizeStrokeViaJev(input: {
+    /** API base including the version segment, e.g. `http://localhost:3000/v1`. */
+    apiBasePath: string | undefined;
+    token: string | null;
+    request: StrokeRecognitionRequest;
+    signal?: AbortSignal;
+}): Promise<CanvasShapeSnapReply | null>;

package/dist/utils/canvasShapeSnapClient.js

@@ -0,0 +1,67 @@
+/**
+ * canvasShapeSnapClient — the Canvas's Jev-backed stroke recognizer.
+ *
+ * When the user draws a shape freehand, the Canvas measures the stroke in code
+ * and decides on its own whenever the measurements are decisive: a drawn
+ * rectangle is a rectangle, with no model and no network. This client covers the
+ * residue — strokes whose measurements leave several shapes standing (a
+ * near-square, an oval that is almost a circle) — by asking the gateway for one
+ * closed-set decision over the measurements and the shapes the geometry allowed.
+ *
+ * The gateway owns the model, the confidence gate, and the rollout mode; this
+ * client only transports and reports. It never throws: a null result means
+ * "leave the stroke exactly as the user drew it", which is what the Canvas does
+ * with no recognizer at all.
+ */
+export async function recognizeStrokeViaJev(input) {
+    if (!input.apiBasePath || !input.token)
+        return null;
+    try {
+        const response = await fetch(`${input.apiBasePath}/agent/shape/recognize`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.token}`
+            },
+            body: JSON.stringify({
+                measurements: input.request.measurements,
+                // Only shapes the client's geometry could not rule out are sent, so
+                // the model can never pick one that is plainly not what was drawn.
+                candidates: input.request.candidates.map((candidate) => ({
+                    shape: candidate.shape,
+                    label: candidate.label,
+                    score: candidate.score
+                })),
+                deterministic: input.request.best
+                    ? { shape: input.request.best.shape, score: input.request.best.score }
+                    : null
+            }),
+            signal: input.signal
+        });
+        if (!response.ok)
+            return null;
+        const json = (await response.json());
+        // The gateway's success envelope is `{ success, data }`; tolerate a bare body.
+        const data = (json?.data ?? json);
+        if (!data || typeof data !== 'object')
+            return null;
+        const source = data.source ?? 'degraded';
+        const reason = String(data.reason ?? '');
+        // `acted` is the only thing that authorizes a replacement: in shadow mode,
+        // on low confidence, or on a degradation the shape is null and the caller
+        // keeps the user's own stroke.
+        if (data.acted !== true || typeof data.shape !== 'string' || !data.shape) {
+            return { source, shape: null, reason, confidence: null };
+        }
+        return {
+            source,
+            shape: data.shape,
+            reason,
+            confidence: typeof data.confidence === 'number' ? data.confidence : null
+        };
+    }
+    catch {
+        // Network/abort/parse failure: leave the stroke as drawn, silently.
+        return null;
+    }
+}

package/dist/utils/designIntentJevClient.d.ts

@@ -0,0 +1,32 @@
+/**
+ * designIntentJevClient — the canvas chat's Jev-backed design resolver fallback.
+ *
+ * The deterministic resolver (`designIntentResolver.ts`) applies explicit values
+ * and arithmetic locally. When it bails, the chat asks the gateway to resolve
+ * the message with JEV: one batched decision over the message plus the
+ * `design.json` roster already loaded here, picking a property and a bounded
+ * value.
+ *
+ * The gateway owns the model, the confidence gate, and the rollout mode; this
+ * client only transports and reports. It never throws and never blocks a send —
+ * a null result means "generate exactly as before".
+ */
+export interface DesignIntentJevResult {
+    /** `jev` = a real verdict; `degraded`/`disabled`/`no_properties` = fallback. */
+    source: 'jev' | 'degraded' | 'disabled' | 'no_properties';
+    /** True only when the gateway confidently resolved a property + value. */
+    acted: boolean;
+    reason: string;
+    property: string | null;
+    value: unknown;
+    confidence: number | null;
+}
+export declare function resolveDesignIntentViaJev(input: {
+    /** API base including the version segment, e.g. `http://localhost:3000/v1`. */
+    apiBasePath: string | undefined;
+    token: string | null;
+    message: string;
+    designSchema: unknown;
+    currentValues: Record<string, unknown>;
+    signal?: AbortSignal;
+}): Promise<DesignIntentJevResult | null>;

package/dist/utils/designIntentJevClient.js

@@ -0,0 +1,51 @@
+/**
+ * designIntentJevClient — the canvas chat's Jev-backed design resolver fallback.
+ *
+ * The deterministic resolver (`designIntentResolver.ts`) applies explicit values
+ * and arithmetic locally. When it bails, the chat asks the gateway to resolve
+ * the message with JEV: one batched decision over the message plus the
+ * `design.json` roster already loaded here, picking a property and a bounded
+ * value.
+ *
+ * The gateway owns the model, the confidence gate, and the rollout mode; this
+ * client only transports and reports. It never throws and never blocks a send —
+ * a null result means "generate exactly as before".
+ */
+export async function resolveDesignIntentViaJev(input) {
+    if (!input.apiBasePath || !input.token)
+        return null;
+    try {
+        const response = await fetch(`${input.apiBasePath}/agent/design/resolve`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${input.token}`,
+            },
+            body: JSON.stringify({
+                message: input.message,
+                designSchema: input.designSchema,
+                currentValues: input.currentValues,
+            }),
+            signal: input.signal,
+        });
+        if (!response.ok)
+            return null;
+        const json = (await response.json());
+        // The gateway's success envelope is `{ success, data }`; tolerate a bare body.
+        const data = (json?.data ?? json);
+        if (!data || typeof data !== 'object')
+            return null;
+        return {
+            source: data.source ?? 'degraded',
+            acted: data.acted === true,
+            reason: String(data.reason ?? ''),
+            property: typeof data.property === 'string' && data.property ? data.property : null,
+            value: data.value ?? null,
+            confidence: typeof data.confidence === 'number' ? data.confidence : null,
+        };
+    }
+    catch {
+        // Network/abort/parse failure: fall through to codegen, silently.
+        return null;
+    }
+}

package/dist/utils/designIntentResolver.d.ts

@@ -0,0 +1,107 @@
+/**
+ * designIntentResolver — deterministic "user wants to change a design property"
+ * resolution, for the canvas chat.
+ *
+ * The canvas chat normally sends every message to codegen (an LLM turn). A large
+ * share of messages are really just design-property tweaks ("make the background
+ * #1a1a2e", "increase the padding by 8", "turn on the border"). Those are fully
+ * decidable in code against the widget's already-loaded `design.json` schema: the
+ * property set is a closed set, and the value is either explicit (hex / number /
+ * boolean / a dropdown option) or an arithmetic transform of the current value.
+ *
+ * This module is intentionally PURE and MODEL-FREE. It never calls JEV or an LLM;
+ * it returns `null` whenever the message needs semantic understanding ("make it
+ * pop", "give it more breathing room") so the caller can fall through to the
+ * existing codegen path. Arithmetic lives here, in code — never in the model.
+ *
+ * Scope: values that are unambiguous and safe to apply to the live preview:
+ *   - colors   (hex, rgb(), and a table of common named colors)
+ *   - numbers  (explicit, or delta/multiplier of the current value; clamped to constraints)
+ *   - booleans (switch/checkbox/radiogroup on|off)
+ *   - dropdown options (by option label/value token)
+ *   - quoted free text (textInput/textArea) — only when explicitly quoted
+ *
+ * Anything else returns null, by design.
+ */
+export interface DesignOption {
+    label: string;
+    value: string;
+}
+/** A design-schema property, flattened from whatever shape the schema uses. */
+export interface DesignPropertyDescriptor {
+    /** Schema key, also the CSS custom-property name used by `widgetic:update`. */
+    id: string;
+    /** Human label from the schema (description || label || id). */
+    label: string;
+    /** Lowercased `inputController.type` (colorpicker, slider, dropdown, ...). */
+    controllerType: string;
+    /** Current value if known, otherwise the schema default. */
+    value: unknown;
+    defaultValue: unknown;
+    options: DesignOption[];
+    min?: number;
+    max?: number;
+    step?: number;
+    helpText?: string;
+}
+export type DesignChangeReason = 'explicit-color' | 'named-color' | 'explicit-number' | 'delta-number' | 'boolean' | 'option' | 'explicit-text';
+export interface DesignChange {
+    propertyId: string;
+    label: string;
+    controllerType: string;
+    previousValue: unknown;
+    value: unknown;
+    reason: DesignChangeReason;
+}
+export interface DesignIntentResolution {
+    changes: DesignChange[];
+    /** Short, human copy for the assistant bubble. */
+    summary: string;
+}
+/** The payload the chat renders as an inline controller card. */
+export interface DesignControlProperty {
+    id: string;
+    label: string;
+    controllerType: string;
+    value: unknown;
+    options?: DesignOption[];
+    min?: number;
+    max?: number;
+    step?: number;
+    helpText?: string;
+}
+export interface DesignControlRequest {
+    summary: string;
+    properties: DesignControlProperty[];
+    /**
+     * The composition this card's control was authored against, when the host
+     * knows it.
+     *
+     * Persisted with the card so a reload can *re-attach* it: the host feeds the
+     * controls the live design values of this composition only, and renders them
+     * read-only while a different one is loaded — otherwise a card from an older
+     * composition would show, and write, whatever the newly selected one holds
+     * under the same property id. Absent on cards created before the field
+     * existed; those stay attached, which is the behaviour that preceded this.
+     */
+    compositionId?: string | null;
+}
+/** Flatten whatever schema shape the codegen produced into a flat property list. */
+export declare function collectDesignProperties(schema: unknown): DesignPropertyDescriptor[];
+/**
+ * Properties the message names (directly or by synonym), strongest first.
+ * Used by the shadow-mode telemetry classifier to bucket a command without
+ * resolving a value for it.
+ */
+export declare function scoreDesignProperties(message: string, schema: unknown): Array<{
+    property: DesignPropertyDescriptor;
+    score: number;
+}>;
+/**
+ * Resolve a chat message into concrete design-property changes, deterministically.
+ * Returns `null` when the message is not an unambiguous, in-scope design tweak —
+ * the caller should then fall through to the existing codegen path.
+ */
+export declare function resolveDesignIntent(message: string, schema: unknown, currentValues?: Record<string, unknown>): DesignIntentResolution | null;
+/** Build the chat card payload from a resolution (used to render inline controls). */
+export declare function toDesignControlRequest(resolution: DesignIntentResolution, schema: unknown, _currentValues?: Record<string, unknown>, compositionId?: string | null): DesignControlRequest;