@happyvertical/smrt-fields 0.40.60 → 0.40.62

package/dist/usage-learning.d.ts

@@ -0,0 +1,201 @@
+import { SmrtObject, SmrtObjectOptions } from '@happyvertical/smrt-core';
+import { DatabaseInterface } from '@happyvertical/sql';
+import { FieldPolicySuggestionKind } from './types.js';
+export interface FieldUsageMaintenanceConfig {
+    /** Drop counter buckets older than this (by `period`). Default 90 days. */
+    counterMaxAgeMs: number;
+    /** Keep at most this many counter rows (oldest pruned first). Default 100k. */
+    counterMaxRows: number;
+    /** Drop ACCEPTED suggestions decided longer ago than this. Default 180 days. */
+    suggestionAcceptedMaxAgeMs: number;
+}
+export declare const FIELD_USAGE_MAINTENANCE_DEFAULTS: FieldUsageMaintenanceConfig;
+export interface FieldUsageSuggestionConfig {
+    /** Usage window the thresholds evaluate over. Default 30 days. */
+    windowDays: number;
+    /** Distinct users required for a `promote` suggestion. Default 5. */
+    minDistinctUsers: number;
+    /** Submissions required before a `default` suggestion. Default 10. */
+    minSetCount: number;
+    /**
+     * Share of windowed submissions a single value must reach for a `default`
+     * suggestion (denominator is TOTAL setCount, so histogram overflow can only
+     * make this more conservative). Default 0.8.
+     */
+    defaultDominanceRatio: number;
+}
+export declare const FIELD_USAGE_SUGGESTION_DEFAULTS: FieldUsageSuggestionConfig;
+export interface FieldUsageMaintenanceSummary {
+    countersPruned: number;
+    receiptsPruned: number;
+    suggestionsPruned: number;
+}
+export interface FieldUsageSuggestionRunSummary {
+    /**
+     * Suggestions this run wrote. Under overlapping runs both may report a
+     * create for the same candidate while the model's active-slot unique index
+     * converges them onto ONE row (see `FieldPolicySuggestion.activeKey`) — the
+     * tally is per-run work, not a row count.
+     */
+    created: number;
+    /** Candidates suppressed by a pending or cooling-down suggestion. */
+    suppressed: number;
+    /** Distinct (tenant, objectRef, fieldName) groups evaluated. */
+    groupsConsidered: number;
+    /**
+     * Groups whose evaluation threw and was skipped. A failing group never
+     * aborts the run — a global pass must keep serving every other tenant.
+     */
+    groupsFailed: number;
+    /**
+     * Bounded sample of failure messages (`MAX_REPORTED_GROUP_FAILURES`) so an
+     * operator can see WHY without the summary growing with the queue.
+     */
+    failures: string[];
+}
+/** Cap on {@link FieldUsageSuggestionRunSummary.failures} entries. */
+export declare const MAX_REPORTED_GROUP_FAILURES = 5;
+export interface FieldUsageCounterRetention {
+    maxAgeMs?: number;
+    maxRows?: number;
+    /** Restrict pruning to one tenant (ambient-context runs). */
+    tenantId?: string | null;
+}
+/**
+ * Prune counter rows to bound growth. Applies whichever bounds are provided
+ * (at least one required): `maxAgeMs` drops buckets whose `period` day is
+ * older than the cutoff; `maxRows` keeps only the newest N rows by
+ * `(period, id)`, deleting oldest-first. Mirrors core's `pruneChangeFeed`.
+ */
+export declare function pruneFieldUsageCounters(db: DatabaseInterface, retention: FieldUsageCounterRetention): Promise<{
+    pruned: number;
+}>;
+/**
+ * Drop durable anti-inflation receipts at the same age cutoff as counters.
+ *
+ * Deliberately do NOT delete a receipt merely because its counter row is
+ * absent: report ingestion claims its receipt before merging the counter, so
+ * an orphan sweep could otherwise reopen the once-per-user/day quota during
+ * that in-flight interval. A max-row counter trim likewise leaves its recent
+ * receipts until the age cutoff — retaining a de-duplication guard is safer
+ * than allowing a second contribution for that day.
+ */
+export declare function pruneFieldUsageReportReceipts(db: DatabaseInterface, options: {
+    maxAgeMs: number;
+    tenantId?: string | null;
+}): Promise<{
+    pruned: number;
+}>;
+export interface FieldPolicySuggestionRetention {
+    /** Drop ACCEPTED suggestions decided longer ago than this. */
+    acceptedMaxAgeMs: number;
+    /** Restrict pruning to one tenant (ambient-context runs). */
+    tenantId?: string | null;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Prune settled suggestion rows ONLY (#2051 pin): a dismissed suggestion once
+ * its cool-down has fully elapsed (its suppression job is done), and an
+ * accepted suggestion once it is old. Pending suggestions are NEVER pruned.
+ */
+export declare function pruneFieldPolicySuggestions(db: DatabaseInterface, retention: FieldPolicySuggestionRetention): Promise<{
+    pruned: number;
+}>;
+export interface RunFieldUsageMaintenanceOptions extends Partial<FieldUsageMaintenanceConfig> {
+    db: DatabaseInterface;
+}
+/**
+ * The "aggregation" schedule's work. Ingestion pre-aggregates into period
+ * buckets, so the roll-up job's real job is retention: prune counter buckets
+ * and durable receipts at the shared age cutoff, then settle old suggestion
+ * rows. Max-row trimming leaves recent receipts intact to preserve daily
+ * de-duplication while an ingestion merge is in flight.
+ */
+export declare function runFieldUsageMaintenance(options: RunFieldUsageMaintenanceOptions): Promise<FieldUsageMaintenanceSummary>;
+export interface RunFieldPolicySuggestionGenerationOptions extends Partial<FieldUsageSuggestionConfig> {
+    db: DatabaseInterface;
+    /** Clock override for deterministic tests. */
+    now?: Date;
+}
+/**
+ * The threshold job: evaluate windowed counters per
+ * `(tenantId, objectRef, fieldName)` and create PENDING suggestions with
+ * human-readable evidence.
+ *
+ * - `promote`: at least `minDistinctUsers` distinct users set the field to a
+ *   non-default value in the window AND the org-resolved visibility is not
+ *   already `basic`.
+ * - `default`: at least `minSetCount` TOTAL submissions, a single recorded
+ *   value covers `defaultDominanceRatio` of those TOTAL submissions (not of
+ *   the deviations — see `FieldUsageCounter.submissionCount`), and it differs
+ *   from the org-resolved default. Only histogram-eligible fields
+ *   (low-cardinality, non-sensitive, non-gated) can ever qualify, and a group
+ *   containing a legacy bucket with no recorded total is skipped rather than
+ *   ratioed against the wrong denominator.
+ *
+ * Dedup: a candidate is suppressed while the same
+ * `(tenantId, objectRef, fieldName, kind)` has a PENDING suggestion or a
+ * DISMISSED one still inside its cool-down. Accepted history never blocks —
+ * once accepted, the resolved policy itself stops regeneration (visibility is
+ * basic / the default matches). The pre-check is an optimization only: the
+ * single-active guarantee is STRUCTURAL (`FieldPolicySuggestion.activeKey` in
+ * `conflictColumns`), so overlapping runs upsert onto one row instead of
+ * duplicating.
+ *
+ * Sensitive, read-permission-gated, and transient fields are skipped
+ * entirely: their usage rows are count-only observability data and never
+ * produce suggestions.
+ */
+export declare function runFieldPolicySuggestionGeneration(options: RunFieldPolicySuggestionGenerationOptions): Promise<FieldUsageSuggestionRunSummary>;
+/**
+ * The registered schedule target for the #2051 learning loop (see the module
+ * doc for why it is NOT an smrt-agents `Agent` subclass). Rows of its system
+ * table are never written — the class exists so `AgentSchedule.agentType`
+ * resolves through the `ObjectRegistry` and smrt-jobs can construct it and
+ * invoke the two allowlisted methods.
+ */
+export declare class FieldUsageLearningAgent extends SmrtObject {
+    /**
+     * The smrt-jobs opt-in background allowlist (S5 contract): ONLY these two
+     * methods are reachable from a persisted job/schedule row.
+     */
+    static backgroundEligibleMethods: ReadonlyArray<string>;
+    constructor(options?: SmrtObjectOptions);
+    /** Schedule entry point for {@link runFieldUsageMaintenance}. */
+    runUsageMaintenance(args?: Record<string, unknown>): Promise<FieldUsageMaintenanceSummary>;
+    /** Schedule entry point for {@link runFieldPolicySuggestionGeneration}. */
+    runSuggestionGeneration(args?: Record<string, unknown>): Promise<FieldUsageSuggestionRunSummary>;
+}
+export interface FieldUsageEvidenceInput {
+    kind: FieldPolicySuggestionKind;
+    objectRef: string;
+    fieldName: string;
+    windowStart: string;
+    windowEnd: string;
+    distinctUsers: number;
+    /** True when the distinct-user set overflowed (count is a lower bound). */
+    distinctUsersAtLeast: boolean;
+    /** Submissions that DIFFERED from the resolved default. */
+    setCount: number;
+    /**
+     * TOTAL submissions observed in the window (the dominance denominator).
+     * `undefined` only for legacy buckets that never recorded a total, in which
+     * case the summary states the deviation count alone.
+     */
+    submissionCount?: number;
+    /** The threshold the candidate cleared (documented in the evidence). */
+    threshold: number;
+    topValue?: unknown;
+    topValueShare?: number;
+}
+/**
+ * Human-readable evidence for a suggestion: a `summary` sentence a reviewer
+ * can read as-is, plus the structured numbers behind it.
+ *
+ * The sentence always states BOTH numbers when known — deviations and total
+ * submissions — so a reviewer can see the base rate a dominance percentage was
+ * computed against instead of trusting a bare ratio.
+ */
+export declare function buildFieldUsageEvidence(input: FieldUsageEvidenceInput): Record<string, unknown>;
+//# sourceMappingURL=usage-learning.d.ts.map

package/dist/usage-learning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-learning.d.ts","sourceRoot":"","sources":["../src/usage-learning.ts"],"names":[],"mappings":"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"}

package/dist/usage-schedules.d.ts

@@ -0,0 +1,110 @@
+import { DatabaseInterface } from '@happyvertical/sql';
+import { FieldUsageMaintenanceConfig, FieldUsageSuggestionConfig } from './usage-learning.js';
+/** Registry-qualified schedule target (`AgentSchedule.agentType`). */
+export declare const FIELD_USAGE_LEARNING_AGENT_TYPE = "@happyvertical/smrt-fields:FieldUsageLearningAgent";
+/** Method the aggregation/retention schedule invokes. */
+export declare const FIELD_USAGE_MAINTENANCE_METHOD = "runUsageMaintenance";
+/** Method the suggestion-generation schedule invokes. */
+export declare const FIELD_USAGE_SUGGESTION_METHOD = "runSuggestionGeneration";
+/**
+ * Default cadence for counter maintenance: daily at 02:30 — in the SCHEDULER
+ * HOST'S LOCAL TIME. See {@link ensureFieldUsageLearningSchedules} for why no
+ * timezone can be selected here.
+ */
+export declare const DEFAULT_FIELD_USAGE_MAINTENANCE_CRON = "30 2 * * *";
+/** Default cadence for suggestion generation: weekly, Monday 03:00 host-local. */
+export declare const DEFAULT_FIELD_USAGE_SUGGESTION_CRON = "0 3 * * 1";
+/**
+ * Stable id for a global learning schedule, derived from the agent type and
+ * method (the `TenantUsageMetric.recordUsage` precedent).
+ *
+ * `_smrt_agent_schedules` has no natural-key uniqueness on
+ * `(agent_type, method)`, so a check-then-create would let two replicas
+ * starting against an empty database each insert their own random-id row —
+ * and with `enabled: true` every job would then run twice. A deterministic id
+ * makes the insert converge on ONE primary key instead.
+ */
+export declare function fieldUsageScheduleId(method: string): Promise<string>;
+/**
+ * Structural surface of the agents module the installer consumes (no static
+ * import — mirrors `FieldPolicyUsersModule`). `create`/`list`/`save` are the
+ * standard SmrtCollection/SmrtObject shapes.
+ */
+export interface FieldUsageAgentsScheduleRow {
+    id?: string | null;
+    enabled?: boolean;
+    /**
+     * Owning tenant; `null`/absent marks the GLOBAL schedules this installer
+     * manages. Read so the existence check cannot mistake a tenant-specific
+     * schedule for the global one.
+     */
+    tenantId?: string | null;
+    save?: () => Promise<unknown>;
+}
+export interface FieldUsageAgentsModule {
+    AgentScheduleCollection: {
+        create(options: {
+            db: DatabaseInterface;
+        }): Promise<{
+            list(options: {
+                where: Record<string, unknown>;
+            }): Promise<FieldUsageAgentsScheduleRow[]>;
+            create(data: Record<string, unknown>): Promise<FieldUsageAgentsScheduleRow>;
+        }>;
+    };
+}
+export interface EnsureFieldUsageLearningSchedulesOptions {
+    db: DatabaseInterface;
+    /**
+     * Whether the schedules start enabled. DEFAULT FALSE — the learning loop
+     * ships dormant; enabling it is an explicit deployment opt-in.
+     */
+    enabled?: boolean;
+    maintenanceCron?: string;
+    suggestionCron?: string;
+    /** Threshold/retention overrides persisted into the schedules' methodArgs. */
+    maintenanceArgs?: Partial<FieldUsageMaintenanceConfig>;
+    suggestionArgs?: Partial<FieldUsageSuggestionConfig>;
+    /** Injection seam for tests / hosts that already loaded the agents module. */
+    agentsModule?: FieldUsageAgentsModule;
+}
+export interface EnsureFieldUsageLearningSchedulesResult {
+    /** False when `@happyvertical/smrt-agents` is not installed (no-op). */
+    installed: boolean;
+    /** Schedules created by THIS call (existing rows are left untouched). */
+    created: number;
+}
+/**
+ * Idempotently create the two GLOBAL (tenant-null) `AgentSchedule` rows for
+ * the learning loop — the aggregation/retention roll-up and the
+ * suggestion-generation job. An existing GLOBAL row for the agent type +
+ * method is never modified (operator state like enable/disable is preserved).
+ *
+ * The existence check is scoped to the GLOBAL rows deliberately: a deployment
+ * may also run tenant-specific schedules for the same agent type and method
+ * (the ambient-context runs the jobs support), and matching one of those would
+ * silently skip installing the global schedule this function promises. Tenant
+ * rows are read but never touched.
+ *
+ * Concurrency: each schedule is written under a DETERMINISTIC id
+ * ({@link fieldUsageScheduleId}) with insert-only semantics, so two replicas
+ * installing at once converge on one row — the pre-check is only the cheap
+ * path, and a primary-key collision is treated as "already installed" rather
+ * than an error. Insert-only also means an existing row's operator state
+ * (enabled/disabled, edited cron) is never overwritten by a later install.
+ *
+ * **No timezone option, deliberately.** `AgentSchedule` carries a `timezone`
+ * column, but `getNextCronDate(cron, _timezone)` ignores the argument and
+ * matches against host-local `getHours()`/`getDate()`, and smrt-jobs'
+ * `ScheduleRunner` recalculates with the same host-local parser. Accepting a
+ * timezone here would advertise control this stack does not have, so these
+ * schedules fire in the SCHEDULER HOST'S LOCAL TIME — pick crons accordingly
+ * (see `agents/usage-learning.md`). Fixing the agents-side parser is out of
+ * scope for this package.
+ *
+ * System operation: global schedules are platform state, so a non-bypass
+ * ambient tenant context is rejected (fail closed) — call this from trusted
+ * startup/migration code.
+ */
+export declare function ensureFieldUsageLearningSchedules(options: EnsureFieldUsageLearningSchedulesOptions): Promise<EnsureFieldUsageLearningSchedulesResult>;
+//# sourceMappingURL=usage-schedules.d.ts.map

package/dist/usage-schedules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-schedules.d.ts","sourceRoot":"","sources":["../src/usage-schedules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAC3B,MAAM,qBAAqB,CAAC;AAG7B,sEAAsE;AACtE,eAAO,MAAM,+BAA+B,uDACU,CAAC;AAEvD,yDAAyD;AACzD,eAAO,MAAM,8BAA8B,wBAAwB,CAAC;AAEpE,yDAAyD;AACzD,eAAO,MAAM,6BAA6B,4BAA4B,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,oCAAoC,eAAe,CAAC;AAEjE,kFAAkF;AAClF,eAAO,MAAM,mCAAmC,cAAc,CAAC;AAE/D;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAMpE;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,uBAAuB,EAAE;QACvB,MAAM,CAAC,OAAO,EAAE;YAAE,EAAE,EAAE,iBAAiB,CAAA;SAAE,GAAG,OAAO,CAAC;YAClD,IAAI,CAAC,OAAO,EAAE;gBACZ,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;aAChC,GAAG,OAAO,CAAC,2BAA2B,EAAE,CAAC,CAAC;YAC3C,MAAM,CACJ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,2BAA2B,CAAC,CAAC;SACzC,CAAC,CAAC;KACJ,CAAC;CACH;AAED,MAAM,WAAW,wCAAwC;IACvD,EAAE,EAAE,iBAAiB,CAAC;IACtB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACvD,cAAc,CAAC,EAAE,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACrD,8EAA8E;IAC9E,YAAY,CAAC,EAAE,sBAAsB,CAAC;CACvC;AAED,MAAM,WAAW,uCAAuC;IACtD,wEAAwE;IACxE,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,iCAAiC,CACrD,OAAO,EAAE,wCAAwC,GAChD,OAAO,CAAC,uCAAuC,CAAC,CAuGlD"}

package/dist/users-module.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared detection for OPTIONAL workspace dependencies
+ * (`@happyvertical/smrt-users`, and since #2051 `@happyvertical/smrt-agents`
+ * for the dormant learning schedules).
+ *
+ * A leaf module (no package-internal imports) so every dynamic-import seam —
+ * the resolver's default tenant-hierarchy loader, the permission catalog
+ * registration, and the schedule installer — shares one matcher without
+ * creating an import cycle through the resolver/collection/model chain.
+ */
+/**
+ * Whether an import failure means the named workspace package is simply not
+ * installed (→ graceful degradation) rather than installed-but-broken
+ * (→ rethrow, surfacing the problem instead of silently degrading).
+ *
+ * The decision is made on the missing-module TARGET parsed from Node's
+ * `Cannot find package/module '<specifier>'` message (walking the full
+ * `cause` chain): only a target that IS the package (or one of its subpaths)
+ * counts. A transitive failure INSIDE an installed package names the other
+ * module as the target — with the package path merely appearing as the
+ * importer — and therefore rethrows. `importWorkspaceModule`'s own
+ * source-fallback wrapper (`Failed to load <packageName> for ...`) is also
+ * accepted: it is thrown only when the package itself cannot be located.
+ *
+ * Exported for direct testing; not re-exported from the package index.
+ */
+export declare function isMissingWorkspaceDependency(error: unknown, packageName: string): boolean;
+/** {@link isMissingWorkspaceDependency} for `@happyvertical/smrt-users`. */
+export declare function isMissingUsersDependency(error: unknown): boolean;
+//# sourceMappingURL=users-module.d.ts.map

package/dist/users-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"users-module.d.ts","sourceRoot":"","sources":["../src/users-module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,OAAO,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAoBT;AAED,4EAA4E;AAC5E,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-fields",
-  "version": "0.40.60",
+  "version": "0.40.62",
   "description": "Layered field policy store and resolver (defaults, visibility tiers, help text) for SMRT objects",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,22 +15,46 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "svelte": "./dist/svelte/index.js",
+      "import": "./dist/svelte/index.js"
+    },
     "./manifest": "./dist/manifest.json",
-    "./manifest.json": "./dist/manifest.json"
+    "./manifest.json": "./dist/manifest.json",
+    "./playground": {
+      "types": "./dist/playground.d.ts",
+      "import": "./dist/playground.js"
+    }
+  },
+  "peerDependencies": {
+    "svelte": "^5.56.4"
+  },
+  "peerDependenciesMeta": {
+    "svelte": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@happyvertical/sql": "^0.85.5",
-    "@happyvertical/smrt-core": "0.40.60",
-    "@happyvertical/smrt-tenancy": "0.40.60"
+    "@happyvertical/smrt-core": "0.40.62",
+    "@happyvertical/smrt-tenancy": "0.40.62",
+    "@happyvertical/smrt-ui": "0.40.62",
+    "@happyvertical/smrt-users": "0.40.62"
   },
   "devDependencies": {
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@testing-library/svelte": "^5.4.2",
     "@types/node": "24.13.2",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
     "typescript": "5.9.3",
     "vite": "8.1.4",
     "vitest": "4.1.10",
-    "@happyvertical/smrt-cli": "0.40.60",
-    "@happyvertical/smrt-users": "0.40.60",
-    "@happyvertical/smrt-vitest": "0.40.60"
+    "@happyvertical/smrt-cli": "0.40.62",
+    "@happyvertical/smrt-users": "0.40.62",
+    "@happyvertical/smrt-vitest": "0.40.62"
   },
   "keywords": [
     "smrt",
@@ -51,8 +75,9 @@
     "directory": "packages/fields"
   },
   "scripts": {
-    "build": "vite build --mode library",
+    "build": "vite build --mode library && svelte-package -i src/svelte -o dist/svelte --tsconfig tsconfig.svelte.json",
     "build:watch": "vite build --mode library --watch",
+    "check": "svelte-check --tsconfig ./tsconfig.svelte.json",
     "clean": "rm -rf dist",
     "dev": "vite dev",
     "test": "vitest run",