@seedgrid/fe-core 2026.4.19 → 2026.4.21

package/dist/http/api-errors.meta.js

@@ -0,0 +1,60 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "utility.api-errors",
+    package: "@seedgrid/fe-core",
+    exportName: "extractApiErrorMessage",
+    slug: "extract-api-error-message",
+    displayName: "API Error Message Extractor",
+    category: "utility",
+    subcategory: "http",
+    description: "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before generic detail/title fields.",
+    tags: ["api", "http", "error", "rfc7807", "validation"],
+    capabilities: [
+        "api-client-error",
+        "rfc7807",
+        "violations",
+        "error-message",
+        "json-string-body",
+    ],
+    fieldSemantics: ["error", "validation", "problem-details", "http"],
+    props: [
+        {
+            name: "error",
+            type: "unknown",
+            required: true,
+            description: "ApiClientError, ApiClientError-like object, Error instance, or unknown thrown value to inspect.",
+            semanticRole: "data",
+        },
+    ],
+    states: ["empty", "problem-details", "violations", "fallback-message"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Showing API validation or problem-detail messages in UI toasts, whistles, dialogs, or notices.",
+        "Normalizing backend RFC7807 responses before mapping them to feature-specific fallback translations.",
+        "Handling cases where errors cross bundle boundaries and no longer satisfy instanceof ApiClientError.",
+    ],
+    avoidUseCases: [
+        "Client-side form validation unrelated to API responses.",
+        "Flows that need full structured problem objects rather than a single human-readable message.",
+    ],
+    synonyms: [
+        "rfc7807 parser",
+        "problem details",
+        "api validation message",
+        "violations message",
+    ],
+    relatedEntityFields: ["responseBody", "detail", "title", "violations", "errors"],
+    compositionHints: [
+        "Call extractApiErrorMessage(error) first, then apply feature-specific server/network/html fallbacks only if needed.",
+        "Use alongside createApiClient so ApiClientError.responseBody is preserved end-to-end.",
+    ],
+    rankingSignals: {
+        freeText: 0.35,
+        structuredChoice: 0.2,
+        date: 0,
+        number: 0,
+        denseLayout: 0.05,
+    },
+};

package/dist/http/api-exception-handler.d.ts

@@ -0,0 +1,15 @@
+export type ExceptionArea = "api" | "client" | "server";
+export type ExceptionContext = {
+    area?: ExceptionArea;
+    source?: string;
+    status?: number;
+    retryable?: boolean;
+    metadata?: Record<string, unknown>;
+};
+export type ExceptionReporter = (error: Error, context: ExceptionContext) => void | Promise<void>;
+export declare function suppressException(error: Error): void;
+export declare function registerExceptionReporter(reporter: ExceptionReporter): () => void;
+export declare function normalizeError(error: unknown): Error;
+export declare function captureException(error: unknown, context?: ExceptionContext): Promise<Error>;
+export declare function runGuarded<T>(action: () => Promise<T> | T, context?: ExceptionContext): Promise<T>;
+//# sourceMappingURL=api-exception-handler.d.ts.map

package/dist/http/api-exception-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exception-handler.d.ts","sourceRoot":"","sources":["../../src/http/api-exception-handler.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,CAC9B,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,gBAAgB,KACtB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAK1B,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,QAE7C;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,iBAAiB,cAMpE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAUpD;AAED,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,gBAAqB,kBAqB/B;AAED,wBAAsB,UAAU,CAAC,CAAC,EAChC,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAC5B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/http/api-exception-handler.js

@@ -0,0 +1,53 @@
+// seedgrid:managed
+const reporters = new Set();
+const CAPTURED_ERROR_SYMBOL = Symbol.for("seedgrid.captured_exception");
+export function suppressException(error) {
+    markAsCaptured(error);
+}
+export function registerExceptionReporter(reporter) {
+    reporters.add(reporter);
+    return () => {
+        reporters.delete(reporter);
+    };
+}
+export function normalizeError(error) {
+    if (error instanceof Error) {
+        return error;
+    }
+    if (typeof error === "string") {
+        return new Error(error);
+    }
+    return new Error("Unknown application error");
+}
+export async function captureException(error, context = {}) {
+    const normalized = normalizeError(error);
+    if (wasCaptured(normalized)) {
+        return normalized;
+    }
+    markAsCaptured(normalized);
+    console.error("[seedgrid]", normalized, context);
+    for (const reporter of reporters) {
+        try {
+            await reporter(normalized, context);
+        }
+        catch (reporterError) {
+            console.error("[seedgrid] reporter failed", reporterError);
+        }
+    }
+    return normalized;
+}
+export async function runGuarded(action, context = {}) {
+    try {
+        return await action();
+    }
+    catch (error) {
+        await captureException(error, context);
+        throw error;
+    }
+}
+function wasCaptured(error) {
+    return Boolean(error[CAPTURED_ERROR_SYMBOL]);
+}
+function markAsCaptured(error) {
+    error[CAPTURED_ERROR_SYMBOL] = true;
+}

package/dist/http/api-exception-handler.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=api-exception-handler.meta.d.ts.map

package/dist/http/api-exception-handler.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-exception-handler.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-exception-handler.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QA+BpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAyBrB,CAAC"}

package/dist/http/api-exception-handler.meta.js

@@ -0,0 +1,57 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "utility.exception-capture",
+    package: "@seedgrid/fe-core",
+    exportName: "captureException",
+    slug: "capture-exception",
+    displayName: "Exception Capture",
+    category: "utility",
+    subcategory: "error-handling",
+    description: "Captures, normalizes, deduplicates, and reports exceptions through registered reporters with contextual metadata.",
+    tags: ["error", "exception", "reporting", "observability", "guard"],
+    capabilities: ["normalize-error", "deduplicate", "reporter-pipeline", "context-metadata"],
+    fieldSemantics: ["error", "exception", "context", "reporting"],
+    props: [
+        {
+            name: "error",
+            type: "unknown",
+            required: true,
+            description: "Unknown thrown value that will be normalized into an Error instance.",
+            semanticRole: "data",
+        },
+        {
+            name: "context",
+            type: "ExceptionContext",
+            required: false,
+            description: "Optional metadata describing area, source, HTTP status, retryability, and extra attributes.",
+            semanticRole: "data",
+        },
+    ],
+    states: ["idle", "captured", "reported", "deduplicated"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Centralized exception capture from UI events, async actions, and API failures.",
+        "Server or client flows that should log/report errors with structured context before rethrowing or translating them.",
+        "Wrapping actions with runGuarded to standardize error capture without repeating try/catch boilerplate.",
+    ],
+    avoidUseCases: [
+        "User-facing validation branches that are expected control flow rather than real exceptions.",
+        "Hot paths where repeated non-error control flow would spam the reporter pipeline.",
+    ],
+    synonyms: ["error capture", "exception reporter", "error guard", "run guarded"],
+    relatedEntityFields: ["error", "exception", "status", "source", "reporting"],
+    compositionHints: [
+        "Register reporters at app bootstrap, then call captureException from feature modules instead of logging ad hoc.",
+        "Use runGuarded around async actions that should always capture and rethrow unexpected failures.",
+        "Use suppressException when an error was intentionally handled and should not be reported again.",
+    ],
+    rankingSignals: {
+        freeText: 0.3,
+        structuredChoice: 0.25,
+        date: 0,
+        number: 0,
+        denseLayout: 0.05,
+    },
+};

package/dist/index.d.ts

@@ -2,4 +2,9 @@ export * from "./module";
 export * from "./registry";
 export * from "./i18n";
 export * from "./persistence";
+export * from "./http/api-exception-handler";
+export * from "./http/api-client";
+export * from "./http/api-errors";
+export * from "./server";
+export * from "./useDebouncedValue";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -2,3 +2,8 @@ export * from "./module";
 export * from "./registry";
 export * from "./i18n";
 export * from "./persistence";
+export * from "./http/api-exception-handler";
+export * from "./http/api-client";
+export * from "./http/api-errors";
+export * from "./server";
+export * from "./useDebouncedValue";

package/dist/persistence-api.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=persistence-api.meta.d.ts.map

package/dist/persistence-api.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-api.meta.d.ts","sourceRoot":"","sources":["../src/persistence-api.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAiDpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA2BrB,CAAC"}

package/dist/persistence-api.meta.js

@@ -0,0 +1,73 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.persistence-api",
+    package: "@seedgrid/fe-core",
+    exportName: "createApiPersistenceStrategy",
+    slug: "create-api-persistence-strategy",
+    displayName: "API Persistence Strategy",
+    category: "hook",
+    subcategory: "persistence",
+    description: "Creates a persistence strategy that syncs application state with a backend API endpoint. Supports custom fetch implementations and versioned state.",
+    tags: ["persistence", "api", "state", "server", "sync"],
+    capabilities: ["persistence", "server-sync", "versioned-state"],
+    fieldSemantics: ["state", "persistence", "api", "backend"],
+    props: [
+        {
+            name: "baseUrl",
+            type: "string",
+            required: true,
+            description: "Base URL of the persistence API (e.g. https://api.example.com/state).",
+            semanticRole: "data",
+        },
+        {
+            name: "fetcher",
+            type: "(input: RequestInfo | URL, init?: RequestInit) => Promise<Response>",
+            required: false,
+            description: "Custom fetch implementation (default: global fetch). Useful for adding auth headers.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "scope",
+            type: "string",
+            required: true,
+            description: "Scope/namespace for the persisted state (e.g. 'app.dashboard', 'user.preferences').",
+            semanticRole: "data",
+        },
+        {
+            name: "stateVersion",
+            type: "number",
+            required: true,
+            description: "Version number of the state schema. Increment when structure changes.",
+            semanticRole: "data",
+        },
+    ],
+    states: ["ready", "loading", "syncing", "error"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Synchronizing application state with a backend server across sessions and devices.",
+        "Multi-device sync where a user's state updates on all their devices.",
+        "Server-side state versioning and schema evolution.",
+    ],
+    avoidUseCases: [
+        "Offline-first applications — use localStorage first, then API (composite strategy).",
+        "High-frequency state updates that would overwhelm the server.",
+        "Real-time collaborative editing — use WebSocket-based persistence instead.",
+    ],
+    synonyms: ["server persistence", "API state sync", "backend storage"],
+    relatedEntityFields: ["persistence", "state", "api", "backend", "sync"],
+    compositionHints: [
+        "Provide a custom fetcher that injects authorization headers if the API requires authentication.",
+        "Use scope to separate user preferences, app state, form cache, etc. on the server.",
+        "Increment stateVersion when the state shape changes to handle schema migrations.",
+        "Pair with createCompositePersistenceStrategy (localStorage primary, API fallback) for resilience.",
+    ],
+    rankingSignals: {
+        freeText: 0.25,
+        structuredChoice: 0.35,
+        date: 0,
+        number: 0,
+        denseLayout: 0.1,
+    },
+};

package/dist/persistence-composite.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=persistence-composite.meta.d.ts.map

package/dist/persistence-composite.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-composite.meta.d.ts","sourceRoot":"","sources":["../src/persistence-composite.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAyCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA8BrB,CAAC"}

package/dist/persistence-composite.meta.js

@@ -0,0 +1,69 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.persistence-composite",
+    package: "@seedgrid/fe-core",
+    exportName: "createCompositePersistenceStrategy",
+    slug: "create-composite-persistence-strategy",
+    displayName: "Composite Persistence Strategy",
+    category: "hook",
+    subcategory: "persistence",
+    description: "Combines two persistence strategies (primary and secondary) with configurable fallback behavior: strict (primary only), fallback (try primary, use secondary on error), or mirror (sync to both simultaneously).",
+    tags: ["persistence", "composite", "fallback", "resilience", "state"],
+    capabilities: ["persistence", "fallback", "resilience", "dual-strategy"],
+    fieldSemantics: ["state", "persistence", "composition"],
+    props: [
+        {
+            name: "mode",
+            type: "'strict' | 'fallback' | 'mirror'",
+            required: true,
+            description: "Mode: 'strict' uses primary only, 'fallback' falls back to secondary on error, 'mirror' syncs to both.",
+            semanticRole: "data",
+        },
+        {
+            name: "primary",
+            type: "PersistenceStrategy",
+            required: true,
+            description: "First-choice persistence strategy (e.g. localStorage for fast local access).",
+            semanticRole: "behavior",
+        },
+        {
+            name: "secondary",
+            type: "PersistenceStrategy",
+            required: true,
+            description: "Fallback or mirror strategy (e.g. API persistence for server sync).",
+            semanticRole: "behavior",
+        },
+    ],
+    states: ["ready", "loading", "syncing", "error"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Resilient offline-first apps: localStorage primary, API fallback.",
+        "Multi-destination state sync: keep local cache and server in sync simultaneously.",
+        "Gradual migration: run old persistence (primary) and new (secondary) in parallel to validate.",
+    ],
+    avoidUseCases: [
+        "Simple applications with only one persistence backend.",
+        "High-frequency updates to avoid bottleneck of syncing both strategies.",
+    ],
+    synonyms: [
+        "dual persistence",
+        "fallback persistence",
+        "hybrid storage",
+        "resilient persistence",
+    ],
+    relatedEntityFields: ["persistence", "state", "fallback", "resilience"],
+    compositionHints: [
+        "Typical offline-first: createLocalStorageStrategy as primary, createApiPersistenceStrategy as secondary with fallback mode.",
+        "Mirror mode enables live sync across devices: load from local cache immediately, update server in background.",
+        "Fallback mode gracefully degrades when API is unavailable — app stays functional using localStorage.",
+    ],
+    rankingSignals: {
+        freeText: 0.2,
+        structuredChoice: 0.4,
+        date: 0,
+        number: 0,
+        denseLayout: 0.15,
+    },
+};

package/dist/persistence-localstorage.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=persistence-localstorage.meta.d.ts.map

package/dist/persistence-localstorage.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persistence-localstorage.meta.d.ts","sourceRoot":"","sources":["../src/persistence-localstorage.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAwBpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA8BrB,CAAC"}