@widgetic/creator 0.3.71 → 0.3.73

package/dist/utils/designIntentResolver.test.js

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import { collectDesignProperties, resolveDesignIntent, toDesignControlRequest } from './designIntentResolver';
+/**
+ * A widget-shaped design schema (the post-codegen shape: one componentGroup,
+ * components carrying `properties`, options under `inputController.config`).
+ */
+const SCHEMA = {
+    componentGroups: [
+        {
+            name: 'Design',
+            components: [
+                {
+                    id: 'appearance',
+                    type: 'layoutGroup',
+                    propertyGroups: [
+                        {
+                            name: 'Colors',
+                            properties: [
+                                {
+                                    id: 'backgroundColor',
+                                    type: 'string',
+                                    defaultValue: '#ffffff',
+                                    inputController: { type: 'colorPicker', description: 'Background Color' }
+                                },
+                                {
+                                    id: 'titleColor',
+                                    type: 'string',
+                                    defaultValue: '#111827',
+                                    inputController: { type: 'colorPicker', description: 'Title Color' }
+                                },
+                                {
+                                    id: 'widgetBorderColor',
+                                    type: 'string',
+                                    defaultValue: '#e5e7eb',
+                                    inputController: { type: 'colorPicker', description: 'Border Color' }
+                                }
+                            ]
+                        },
+                        {
+                            name: 'Spacing',
+                            properties: [
+                                {
+                                    id: 'padding',
+                                    type: 'number',
+                                    defaultValue: 16,
+                                    inputController: { type: 'slider', description: 'Padding', config: { min: 0, max: 64, step: 1 } }
+                                },
+                                {
+                                    id: 'borderRadius',
+                                    type: 'number',
+                                    defaultValue: 8,
+                                    inputController: { type: 'number', description: 'Border Radius', config: { min: 0, max: 40, step: 1 } }
+                                }
+                            ]
+                        },
+                        {
+                            name: 'Layout',
+                            properties: [
+                                {
+                                    id: 'layout',
+                                    type: 'string',
+                                    defaultValue: 'grid',
+                                    inputController: {
+                                        type: 'dropdown',
+                                        description: 'Layout Style',
+                                        config: {
+                                            options: [
+                                                { label: 'Grid', value: 'grid' },
+                                                { label: 'List', value: 'list' },
+                                                { label: 'Carousel', value: 'carousel' }
+                                            ]
+                                        }
+                                    }
+                                },
+                                {
+                                    id: 'showShadow',
+                                    type: 'boolean',
+                                    defaultValue: true,
+                                    inputController: { type: 'switch', description: 'Drop Shadow' }
+                                },
+                                {
+                                    id: 'widgetTitle',
+                                    type: 'string',
+                                    defaultValue: 'My Widget',
+                                    inputController: { type: 'textInput', description: 'Widget Title' }
+                                }
+                            ]
+                        }
+                    ]
+                }
+            ]
+        }
+    ]
+};
+const LIVE = { backgroundColor: '#ffffff', padding: 16, borderRadius: 8, showShadow: true };
+describe('collectDesignProperties', () => {
+    it('flattens nested property groups into descriptors', () => {
+        const props = collectDesignProperties(SCHEMA);
+        expect(props.map((p) => p.id)).toEqual([
+            'backgroundColor',
+            'titleColor',
+            'widgetBorderColor',
+            'padding',
+            'borderRadius',
+            'layout',
+            'showShadow',
+            'widgetTitle'
+        ]);
+    });
+    it('reads dropdown options from inputController.config.options', () => {
+        const dropdown = collectDesignProperties(SCHEMA).find((p) => p.id === 'layout');
+        expect(dropdown?.options).toHaveLength(3);
+        expect(dropdown?.options[1]).toEqual({ label: 'List', value: 'list' });
+    });
+    it('reads numeric constraints', () => {
+        const padding = collectDesignProperties(SCHEMA).find((p) => p.id === 'padding');
+        expect(padding).toMatchObject({ min: 0, max: 64, step: 1 });
+    });
+});
+describe('resolveDesignIntent — colors', () => {
+    it('resolves an explicit hex on the named color property', () => {
+        const r = resolveDesignIntent('make the background #1a1a2e', SCHEMA, LIVE);
+        expect(r?.changes).toHaveLength(1);
+        expect(r?.changes[0]).toMatchObject({
+            propertyId: 'backgroundColor',
+            value: '#1a1a2e',
+            reason: 'explicit-color'
+        });
+    });
+    it('expands 3-digit hex', () => {
+        const r = resolveDesignIntent('set the background to #abc', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe('#aabbcc');
+    });
+    it('resolves a named color', () => {
+        const r = resolveDesignIntent('change the background to red', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'backgroundColor', value: '#ff0000', reason: 'named-color' });
+    });
+    it('resolves rgb()', () => {
+        const r = resolveDesignIntent('background rgb(26, 26, 46)', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe('#1a1a2e');
+    });
+    it('does not touch a number property when only a color is given', () => {
+        const r = resolveDesignIntent('make the padding red', SCHEMA, LIVE);
+        expect(r).toBeNull();
+    });
+});
+describe('resolveDesignIntent — numbers (arithmetic stays in code)', () => {
+    it('sets an explicit number', () => {
+        const r = resolveDesignIntent('set the border radius to 12', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'borderRadius', value: 12, reason: 'explicit-number' });
+    });
+    it('increases by an absolute delta using the current value', () => {
+        const r = resolveDesignIntent('increase the padding by 8', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'padding', value: 24, reason: 'delta-number' });
+    });
+    it('applies a percentage delta', () => {
+        const r = resolveDesignIntent('reduce the padding by 25%', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe(12);
+    });
+    it('doubles the current value', () => {
+        const r = resolveDesignIntent('double the border radius', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe(16);
+    });
+    it('halves the current value', () => {
+        const r = resolveDesignIntent('half the padding', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe(8);
+    });
+    it('clamps to the schema max', () => {
+        const r = resolveDesignIntent('increase the padding by 500', SCHEMA, LIVE);
+        expect(r?.changes[0].value).toBe(64);
+    });
+    it('uses the schema default when no live value is supplied', () => {
+        const r = resolveDesignIntent('increase the padding by 4', SCHEMA);
+        expect(r?.changes[0]).toMatchObject({ previousValue: 16, value: 20 });
+    });
+});
+describe('resolveDesignIntent — booleans and options', () => {
+    it('turns a switch on', () => {
+        const r = resolveDesignIntent('turn the drop shadow off', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'showShadow', value: false, reason: 'boolean' });
+    });
+    it('enables', () => {
+        const r = resolveDesignIntent('enable the shadow', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'showShadow', value: true });
+    });
+    it('selects a dropdown option by label', () => {
+        const r = resolveDesignIntent('switch the layout to carousel', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'layout', value: 'carousel', reason: 'option' });
+    });
+});
+describe('resolveDesignIntent — text', () => {
+    it('resolves only explicitly quoted text', () => {
+        const r = resolveDesignIntent('set the widget title to "Grocery list"', SCHEMA, LIVE);
+        expect(r?.changes[0]).toMatchObject({ propertyId: 'widgetTitle', value: 'Grocery list' });
+    });
+    it('refuses unquoted text (falls through to codegen)', () => {
+        expect(resolveDesignIntent('change the title to grocery list', SCHEMA, LIVE)).toBeNull();
+    });
+});
+describe('resolveDesignIntent — bails out (falls through to codegen/JEV)', () => {
+    it('returns null for vague intent', () => {
+        expect(resolveDesignIntent('make it pop', SCHEMA, LIVE)).toBeNull();
+        expect(resolveDesignIntent('give it more breathing room', SCHEMA, LIVE)).toBeNull();
+        expect(resolveDesignIntent('make it feel more premium', SCHEMA, LIVE)).toBeNull();
+    });
+    it('returns null for a color with no named property', () => {
+        expect(resolveDesignIntent('make it red', SCHEMA, LIVE)).toBeNull();
+    });
+    it('returns null for a non-design ask', () => {
+        expect(resolveDesignIntent('add a confetti animation when the timer ends', SCHEMA, LIVE)).toBeNull();
+    });
+    it('returns null when two properties tie on name match', () => {
+        // "color" alone names all three color properties equally → ambiguous.
+        expect(resolveDesignIntent('change the color to red', SCHEMA, LIVE)).toBeNull();
+    });
+    it('returns null for an empty schema', () => {
+        expect(resolveDesignIntent('make the background red', {}, LIVE)).toBeNull();
+    });
+});
+describe('toDesignControlRequest', () => {
+    it('carries the resolved value + constraints for the inline controller', () => {
+        const r = resolveDesignIntent('increase the padding by 8', SCHEMA, LIVE);
+        const card = toDesignControlRequest(r, SCHEMA, LIVE);
+        expect(card.summary).toContain('Padding');
+        expect(card.properties[0]).toMatchObject({
+            id: 'padding',
+            controllerType: 'slider',
+            value: 24,
+            min: 0,
+            max: 64
+        });
+    });
+    it('records the composition the change landed in, so a reload can re-attach it', () => {
+        const r = resolveDesignIntent('increase the padding by 8', SCHEMA, LIVE);
+        expect(toDesignControlRequest(r, SCHEMA, LIVE, 'composition-1').compositionId).toBe('composition-1');
+    });
+    it('omits the composition rather than recording null when there is none', () => {
+        // A card persisted before the field existed, and one authored against a
+        // composition that was never saved, both arrive without it — and the host
+        // treats exactly that shape as "attached".
+        const r = resolveDesignIntent('increase the padding by 8', SCHEMA, LIVE);
+        expect(toDesignControlRequest(r, SCHEMA, LIVE)).not.toHaveProperty('compositionId');
+        expect(toDesignControlRequest(r, SCHEMA, LIVE, null)).not.toHaveProperty('compositionId');
+        expect(toDesignControlRequest(r, SCHEMA, LIVE, '')).not.toHaveProperty('compositionId');
+    });
+});

package/dist/utils/designIntentTelemetry.d.ts

@@ -0,0 +1,176 @@
+/**
+ * designIntentTelemetry — shadow-mode measurement for the canvas chat.
+ *
+ * Every message a user sends in the canvas chat is bucketed by *how it could be
+ * resolved*, independently of what the app actually does:
+ *
+ *   literal_arithmetic   — explicit value / arithmetic in code (the deterministic
+ *                          resolver already handles it; no model needed)
+ *   bounded_set_semantic — a design ask whose property/value needs judgment
+ *                          (the JEV-shaped residual: Choice over the closed set)
+ *   free_text            — needs a text value (an LLM)
+ *   new_property         — asks for a design property that does not exist yet
+ *                          (generation; an LLM)
+ *   not_design           — not a design tweak at all → codegen as today
+ *
+ * This module is measurement only: it never applies a change and never alters a
+ * send. It records one event per message, persists rolling counts so fractions
+ * survive reloads, and reports them. Enabling it is safe in production.
+ *
+ * The Jev fallback is measured twice over: how big its candidate pool is (the
+ * bounded-set-semantic bucket) and how much of that pool it resolves. Every dial
+ * is attributed to the *ask shape* that produced it, so a fall-through count can
+ * be read against the question it implicates — a weak value bucket and a weak
+ * property roster produce entirely different reasons — instead of as one global
+ * total.
+ */
+export type DesignIntentBucket = 'literal_arithmetic' | 'bounded_set_semantic' | 'free_text' | 'new_property' | 'not_design';
+export declare const DESIGN_INTENT_BUCKETS: DesignIntentBucket[];
+/**
+ * The two shapes a bounded-set-semantic ask arrives in. Which one it is decides
+ * what a fall-through implicates, because a different question carries the
+ * weight in each:
+ *
+ *   property_name — the message named a property, so the **value** question is
+ *                   under test: `low_confidence_value` / `no_value_stated` point
+ *                   at the value option strings.
+ *   value_only    — only a value was stated and which property it targets needs
+ *                   judgment, so the **property** question is: `low_confidence`
+ *                   / `none_of_these` point at the property option strings or
+ *                   the confidence floor.
+ */
+export type DesignIntentAskShape = 'property_named' | 'value_only';
+/** Every ask shape, plus dials that outlived their classification (a refresh
+ *  mid-conversation, or counts persisted before shapes were recorded). */
+export type DesignIntentJevShape = DesignIntentAskShape | 'unknown';
+export declare const JE_ASK_SHAPES: DesignIntentJevShape[];
+export interface DesignIntentClassification {
+    bucket: DesignIntentBucket;
+    /** Design properties the message named (empty when nothing matched). */
+    propertyIds: string[];
+    detail: string;
+    /** Set on the bounded-set-semantic bucket only — the shape is what Jev's
+     *  reason counts are read against. */
+    shape?: DesignIntentAskShape;
+}
+/**
+ * Bucket a single chat message. Pure and deterministic — the same heuristics the
+ * resolver uses for property naming, plus a few value/verb signals.
+ */
+export declare function classifyDesignIntent(message: string, schema: unknown): DesignIntentClassification;
+export interface DesignIntentTelemetryEvent extends DesignIntentClassification {
+    messageLength: number;
+    at: number;
+}
+/** One ask shape's slice of the Jev dials. */
+export interface DesignIntentJevShapeBreakdown {
+    attempts: number;
+    acted: number;
+    fellThrough: number;
+    /** `acted / attempts`, 0 when this shape was never dialed. */
+    resolvedShare: number;
+    byReason: Record<string, number>;
+}
+export interface DesignIntentJevSnapshot {
+    /** Jev dials attempted on the bounded-set-semantic bucket. */
+    attempts: number;
+    /** Dials whose verdict was applied (enforce mode + confident + bounded value). */
+    acted: number;
+    /** Dials that fell through to codegen, for any reason. */
+    fellThrough: number;
+    /** `acted / attempts`, 0 when nothing was attempted. */
+    resolvedShare: number;
+    /** Fall-through (or acted) reasons, for tuning the questions and the gates. */
+    byReason: Record<string, number>;
+    /** The same counters split by ask shape, so a reason count can be read against
+     *  the question that produced it rather than as a global total. */
+    byShape: Record<DesignIntentJevShape, DesignIntentJevShapeBreakdown>;
+    /** Dials attributed to a bucket other than the one the design says is ever
+     *  dialed. Should stay 0: a non-zero value means a dial is happening where the
+     *  module claims it cannot, so it is counted rather than folded in. */
+    offBucketDials: number;
+}
+export interface DesignIntentTelemetrySnapshot {
+    /** Every recorded send, including ones with no design schema loaded. */
+    total: number;
+    /** Sends that could be classified (a design schema was loaded). */
+    counted: number;
+    /** Sends recorded while no design schema was available (unclassifiable). */
+    noSchema: number;
+    buckets: Record<DesignIntentBucket, number>;
+    /** Share of `counted` per bucket, 0–1. */
+    fractions: Record<DesignIntentBucket, number>;
+    /** Share of `counted` the deterministic path could have applied. */
+    deterministicShare: number;
+    /** Share of `counted` that is a design ask needing a model (JEV or LLM). */
+    modelShare: number;
+    /** How the Jev fallback fared on its one candidate bucket. */
+    jev: DesignIntentJevSnapshot;
+}
+/**
+ * The one bucket Jev is asked about. It is the residual where a design property
+ * or value needs judgment but the value space is closed — `free_text` and
+ * `new_property` can only fall through (Jev cannot generate), and `not_design`
+ * is not a design ask at all, so neither is ever dialed.
+ */
+export declare const JEV_CANDIDATE_BUCKET: DesignIntentBucket;
+export declare function isJevCandidateBucket(bucket: DesignIntentBucket | null | undefined): boolean;
+export type DesignIntentJevSource = 'jev' | 'degraded' | 'disabled' | 'no_properties' | 'client_unavailable';
+/** The on-disk shape of one ask shape's counters — exported because loading it
+ *  is a migration, and a migration is worth asserting on directly. */
+export interface PersistedShapeBreakdown {
+    attempts: number;
+    acted: number;
+    fellThrough: number;
+    byReason: Record<string, number>;
+}
+/** The persisted Jev counters. `byShape` and `offBucketDials` were added after
+ *  the first version of this payload shipped, so a stored payload from before
+ *  them must still load — see `parsePersistedTelemetry`. */
+export interface PersistedJev {
+    attempts: number;
+    acted: number;
+    fellThrough: number;
+    byReason: Record<string, number>;
+    byShape: Record<DesignIntentJevShape, PersistedShapeBreakdown>;
+    offBucketDials: number;
+}
+/** The whole persisted payload, as stored under `STORAGE_KEY`. */
+export interface PersistedDesignIntentTelemetry {
+    total: number;
+    noSchema: number;
+    buckets: Record<DesignIntentBucket, number>;
+    jev: PersistedJev;
+}
+/**
+ * Parse one persisted payload. Pure, so the upgrade path — every shape recorded
+ * before `byShape` existed — is testable without a browser: counts that are
+ * absent, negative or not numbers become zero, and the flat reason map it does
+ * have is kept.
+ */
+export declare function parsePersistedTelemetry(raw: string | null): PersistedDesignIntentTelemetry;
+/**
+ * Record one canvas-chat send and bucket it. Shadow mode: this does not change
+ * any behavior — the caller generates exactly as it did before. Returns the
+ * classification so a caller could log or assert on it.
+ */
+export declare function recordDesignIntentTelemetry(message: string, schema: unknown): DesignIntentClassification;
+/**
+ * Record the outcome of one Jev fallback dial. This closes the measurement
+ * loop: the bucketing tells us how big the candidate pool is, and this tells us
+ * how much of it Jev actually resolves — the number that earns the flip from
+ * `shadow` to `enforce`.
+ */
+export declare function recordDesignIntentJevOutcome(outcome: {
+    source: DesignIntentJevSource;
+    acted: boolean;
+    reason: string;
+    /** The classification of the send that triggered this dial. Without it the
+     *  dial is counted, but under `unknown` rather than guessed into a shape. */
+    classification?: Pick<DesignIntentClassification, 'bucket' | 'shape'> | null;
+}): void;
+export declare function getDesignIntentTelemetrySnapshot(): DesignIntentTelemetrySnapshot;
+export declare function formatDesignIntentTelemetryReport(snapshot: DesignIntentTelemetrySnapshot): string;
+/** Recent events (last 100, newest last) — for a quick look in the console. */
+export declare function getRecentDesignIntentEvents(): DesignIntentTelemetryEvent[];
+export declare function resetDesignIntentTelemetry(): void;