@seedgrid/fe-core 2026.4.18 → 2026.4.20

package/dist/ai/seedgrid-core.manifest.json

@@ -0,0 +1,649 @@
+{
+  "schemaVersion": "0.1",
+  "package": "@seedgrid/fe-core",
+  "packageVersion": "0.2.0",
+  "components": [
+    {
+      "componentId": "provider.registry",
+      "exportName": "SeedGridRegistry",
+      "sgMeta": {
+        "version": "0.1",
+        "componentId": "provider.registry",
+        "package": "@seedgrid/fe-core",
+        "exportName": "SeedGridRegistry",
+        "slug": "seedgrid-registry",
+        "displayName": "SeedGrid Registry",
+        "category": "provider",
+        "subcategory": "registry",
+        "description": "Centralized provider and route registry for modular SeedGrid applications. Manages composition of providers, navigation items, and routes with ordering support.",
+        "tags": [
+          "registry",
+          "provider",
+          "composition",
+          "modular",
+          "architecture"
+        ],
+        "capabilities": [
+          "navItem",
+          "provider",
+          "route",
+          "ordering"
+        ],
+        "fieldSemantics": [
+          "registry",
+          "composition",
+          "navigation"
+        ],
+        "props": [
+          {
+            "name": "addProvider",
+            "type": "(provider: SeedGridProvider) => void",
+            "required": true,
+            "description": "Register a React provider component (context wrapper).",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "addNavItem",
+            "type": "(item: SeedGridNavItem) => void",
+            "required": true,
+            "description": "Register a navigation item with id, labelKey, href, optional icon and order.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "addRoute",
+            "type": "(route: SeedGridRoute) => void",
+            "required": true,
+            "description": "Register an application route with id, path, and auth requirements.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "getProviders",
+            "type": "() => SeedGridProvider[]",
+            "required": true,
+            "description": "Retrieve all registered providers as a flat array.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "getNavItems",
+            "type": "() => SeedGridNavItem[]",
+            "required": true,
+            "description": "Retrieve all registered navigation items sorted by order (default 999).",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "getRoutes",
+            "type": "() => SeedGridRoute[]",
+            "required": true,
+            "description": "Retrieve all registered routes.",
+            "semanticRole": "behavior"
+          }
+        ],
+        "states": [
+          "initialized",
+          "empty",
+          "populated"
+        ]
+      },
+      "aiHints": {
+        "version": "0.1",
+        "preferredUseCases": [
+          "Modular application architecture where features register themselves independently.",
+          "Dynamic provider composition to avoid prop drilling and provider hell.",
+          "Centralized routing and navigation configuration across modules."
+        ],
+        "avoidUseCases": [
+          "Simple single-feature applications that don't need modular composition.",
+          "Direct React Context usage when a single provider suffices."
+        ],
+        "synonyms": [
+          "module registry",
+          "provider registry",
+          "app composer",
+          "navigation builder"
+        ],
+        "relatedEntityFields": [
+          "module",
+          "provider",
+          "navigation",
+          "route",
+          "composition"
+        ],
+        "compositionHints": [
+          "Registry is typically paired with SeedGridModuleManifest for self-contained module definitions.",
+          "Providers registered to the registry should be wrapped to inject dependencies from environment/core.",
+          "Order-based nav item sorting enables feature modules to control their menu position without cross-module coupling."
+        ],
+        "rankingSignals": {
+          "freeText": 0.3,
+          "structuredChoice": 0.4,
+          "date": 0,
+          "number": 0,
+          "denseLayout": 0.2
+        }
+      }
+    },
+    {
+      "componentId": "hook.persistence-localstorage",
+      "exportName": "createLocalStorageStrategy",
+      "sgMeta": {
+        "version": "0.1",
+        "componentId": "hook.persistence-localstorage",
+        "package": "@seedgrid/fe-core",
+        "exportName": "createLocalStorageStrategy",
+        "slug": "create-localstorage-strategy",
+        "displayName": "Local Storage Persistence Strategy",
+        "category": "hook",
+        "subcategory": "persistence",
+        "description": "Creates a persistence strategy that stores and retrieves application state from browser localStorage with optional key prefix.",
+        "tags": [
+          "persistence",
+          "storage",
+          "state",
+          "localStorage",
+          "browser"
+        ],
+        "capabilities": [
+          "persistence",
+          "offline",
+          "browser-native"
+        ],
+        "fieldSemantics": [
+          "state",
+          "persistence",
+          "storage"
+        ],
+        "props": [
+          {
+            "name": "options",
+            "type": "{ prefix?: string }",
+            "required": false,
+            "description": "Optional configuration: prefix for localStorage keys (default: no prefix).",
+            "semanticRole": "data"
+          }
+        ],
+        "states": [
+          "ready",
+          "loading",
+          "error"
+        ]
+      },
+      "aiHints": {
+        "version": "0.1",
+        "preferredUseCases": [
+          "Client-side application state persistence across browser sessions.",
+          "Caching user preferences, form state, or temporary data in the browser.",
+          "Single-origin applications where cross-origin data sharing is not needed."
+        ],
+        "avoidUseCases": [
+          "Sensitive data (passwords, tokens) — use secure server-side persistence instead.",
+          "Large datasets that exceed localStorage limit (~5-10MB per origin).",
+          "Server-synchronized state that requires real-time consistency across tabs."
+        ],
+        "synonyms": [
+          "browser persistence",
+          "local storage strategy",
+          "client-side state storage"
+        ],
+        "relatedEntityFields": [
+          "persistence",
+          "state",
+          "storage",
+          "caching"
+        ],
+        "compositionHints": [
+          "Use prefix option to namespace data when multiple apps share the same origin.",
+          "Combine with createCompositePersistenceStrategy to fall back to API persistence on failure.",
+          "State should be serializable to JSON — complex objects are converted via stringify."
+        ],
+        "rankingSignals": {
+          "freeText": 0.2,
+          "structuredChoice": 0.3,
+          "date": 0,
+          "number": 0,
+          "denseLayout": 0.1
+        }
+      }
+    },
+    {
+      "componentId": "hook.persistence-api",
+      "exportName": "createApiPersistenceStrategy",
+      "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"
+        ]
+      },
+      "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
+        }
+      }
+    },
+    {
+      "componentId": "hook.persistence-composite",
+      "exportName": "createCompositePersistenceStrategy",
+      "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"
+        ]
+      },
+      "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
+        }
+      }
+    },
+    {
+      "componentId": "factory.api-client",
+      "exportName": "createApiClient",
+      "sgMeta": {
+        "version": "0.1",
+        "componentId": "factory.api-client",
+        "package": "@seedgrid/fe-core",
+        "exportName": "createApiClient",
+        "slug": "create-api-client",
+        "displayName": "API Client Factory",
+        "category": "factory",
+        "subcategory": "http",
+        "description": "Factory function that creates a fetch-based API client with auth token injection, retry policies, response parsing, cURL debug output, and typed request helpers.",
+        "tags": [
+          "api",
+          "http",
+          "fetch",
+          "auth",
+          "retry",
+          "json"
+        ],
+        "capabilities": [
+          "get",
+          "post",
+          "put",
+          "patch",
+          "delete",
+          "refresh-token",
+          "response-parse",
+          "query-params"
+        ],
+        "fieldSemantics": [
+          "api",
+          "request",
+          "authentication",
+          "retry",
+          "error-handling"
+        ],
+        "props": [
+          {
+            "name": "baseUrl",
+            "type": "string",
+            "required": true,
+            "description": "Base URL used to resolve relative API paths.",
+            "semanticRole": "data"
+          },
+          {
+            "name": "getAccessToken",
+            "type": "() => Promise<string | null>",
+            "required": false,
+            "description": "Async callback used to read the current access token before authenticated requests.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "refreshAccessToken",
+            "type": "() => Promise<string | null>",
+            "required": false,
+            "description": "Async callback used after a 401 to obtain a fresh access token and retry once.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "defaultHeaders",
+            "type": "HeadersInit",
+            "required": false,
+            "description": "Headers merged into every request before per-request overrides.",
+            "semanticRole": "data"
+          },
+          {
+            "name": "defaultCache",
+            "type": "RequestCache",
+            "required": false,
+            "description": "Default fetch cache mode used when a request does not override cache.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "defaultNext",
+            "type": "{ revalidate?: false | number; tags?: string[] }",
+            "required": false,
+            "description": "Next.js fetch options reused across requests.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "onAuthFailure",
+            "type": "(context: ExceptionContext) => void | Promise<void>",
+            "required": false,
+            "description": "Optional callback fired when an authenticated request still fails with 401.",
+            "semanticRole": "event"
+          },
+          {
+            "name": "onException",
+            "type": "(error: Error, context: ExceptionContext) => void | Promise<void>",
+            "required": false,
+            "description": "Optional callback invoked before captured API exceptions are rethrown.",
+            "semanticRole": "event"
+          }
+        ],
+        "states": [
+          "ready",
+          "requesting",
+          "retrying",
+          "failed"
+        ]
+      },
+      "aiHints": {
+        "version": "0.1",
+        "preferredUseCases": [
+          "Server or client HTTP access where auth tokens, retries, and typed JSON parsing should be standardized.",
+          "Application modules that need consistent GET/POST/PUT/PATCH/DELETE helpers instead of ad hoc fetch calls.",
+          "Next.js integrations that need cache/next options to flow through a shared API layer."
+        ],
+        "avoidUseCases": [
+          "Very small one-off fetch calls where a dedicated client adds no value.",
+          "Streaming or multipart-heavy workflows that need low-level fetch control."
+        ],
+        "synonyms": [
+          "api client",
+          "fetch wrapper",
+          "http client",
+          "authenticated fetch",
+          "request factory"
+        ],
+        "relatedEntityFields": [
+          "api",
+          "request",
+          "auth",
+          "token",
+          "retry",
+          "http"
+        ],
+        "compositionHints": [
+          "Pair createApiClient with captureException or module-level error translation when surfacing server errors to the UI.",
+          "Use requireAuth: false for public endpoints; leave it enabled by default for private endpoints.",
+          "Use parseAs: 'response' when the caller needs raw headers or binary body handling."
+        ],
+        "rankingSignals": {
+          "freeText": 0.35,
+          "structuredChoice": 0.3,
+          "date": 0,
+          "number": 0.05,
+          "denseLayout": 0.1
+        }
+      }
+    },
+    {
+      "componentId": "utility.exception-capture",
+      "exportName": "captureException",
+      "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"
+        ]
+      },
+      "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
+        }
+      }
+    }
+  ]
+}