@declarion/react 0.1.65 → 0.1.68

package/dist-lib/lib/rich-text.d.ts

@@ -0,0 +1,14 @@
+import type { HydratedFile } from "../types/files";
+export interface RichTextValue {
+    markdown: string;
+    files: Record<string, HydratedFile>;
+}
+export declare function richTextMarkdown(value: unknown): string;
+export declare function richTextFiles(value: unknown): Record<string, HydratedFile>;
+export declare function createRichTextValue(markdownValue: unknown, inlineFilesValue: unknown): RichTextValue;
+export declare function withRichTextFile(value: unknown, file: HydratedFile): RichTextValue;
+export declare function withoutRichTextFiles(value: unknown, removedIds: Iterable<string>): RichTextValue;
+export declare function inlineFilesById(value: unknown): Record<string, HydratedFile>;
+export declare function extractDeclarionFileIds(markdown: string): string[];
+export declare function extractDeclarionFileId(url: string | undefined): string | null;
+export declare function richTextTokenForFile(file: Pick<HydratedFile, "id" | "content_type" | "filename">): string;

package/dist-lib/lib/safe-url.d.ts

@@ -0,0 +1 @@
+export declare function safeExternalUrl(input: string | undefined | null): string | undefined;

package/dist-lib/lib/timestamp.d.ts

@@ -18,3 +18,20 @@ export declare function formatWireDateTime(date?: Date): string;
  * Falls back to browser-local formatting for bare datetime strings.
  */
 export declare function formatOffsetTimestamp(raw: string): string;
+/**
+ * Relative-or-absolute timestamp formatting for the time_ago cell renderer.
+ *
+ * Returns a short relative phrase ("5 minutes ago", "2 days ago") when the
+ * timestamp is within the last 30 days, and an ISO date ("2026-01-15") when
+ * older. Linear / Stripe / Datadog convention — avoids the "1y 4mo 12d ago"
+ * eyesore for stable historical data.
+ *
+ * `absolute` is the offset-aware long form intended for the cell's hover
+ * tooltip; the user always has access to the precise timestamp.
+ *
+ * Bare or unparseable input falls back to the raw string for both fields.
+ */
+export declare function formatRelativeOrAbsolute(raw: string | Date | null | undefined, now?: Date): {
+    text: string;
+    absolute: string;
+};

package/dist-lib/lib/versionTracker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * versionTracker — central staleness-detection state for the SPA.
+ *
+ * Every API response carries `X-Declarion-Version: <combined-fingerprint>`
+ * (set by the server's version_header middleware). The FIRST arrival
+ * in a bundle's lifetime is captured as the baseline; any later
+ * response with a different value triggers drift detection — the SPA
+ * either silently invalidates the schema query (if only schema differs)
+ * or prompts the user to reload (if assets/binary changed).
+ *
+ * **State is in-memory only — no sessionStorage / localStorage.** Each
+ * bundle load captures its own baseline from its first response. The
+ * bundle IS its own version contract; the live server's first answer
+ * defines what version the bundle should consider itself. Persisting
+ * across reloads is actively harmful: a stale baseline from a previous
+ * bundle could override the live answer, producing a "click Reload →
+ * page reloads → toast pops again" infinite loop. This is the same
+ * lesson behind why `index.html` is `Cache-Control: no-cache` — the
+ * bootstrap manifest must always be live, never replayed.
+ *
+ * Defense in depth runs three sources into the same comparator:
+ *   1. observe() — header read on every API response (apiFetch hook).
+ *   2. fetchProbe() — explicit GET /api/version (focus / online / 60s).
+ *   3. (optional) SSE `version-changed` event from useSSE.
+ *
+ * Cross-tab coordination via BroadcastChannel('declarion-version') —
+ * runtime IPC only, not persistence. When one tab detects drift it
+ * fans the decision out so all tabs reload together (avoids the
+ * half-old / half-new tab anti-pattern). Each tab still bootstraps
+ * its own baseline independently.
+ */
+export interface VersionDelta {
+    /** Reason the delta was emitted. Lets subscribers decide UX. */
+    kind: "schema-only" | "asset-or-binary" | "unknown";
+    /** Latest combined fingerprint observed. Drives the next baseline. */
+    observed: string;
+    /** Per-component breakdown when /api/version was reached. */
+    components?: VersionComponents;
+}
+export interface VersionComponents {
+    schema: string;
+    asset: string;
+    binary: string;
+}
+export type VersionDeltaListener = (delta: VersionDelta) => void;
+/**
+ * Observe an API response. Captures the first-seen fingerprint and
+ * compares subsequent ones. Idempotent — safe to call from every
+ * apiFetch round-trip; backward-compatible — no-op when the header
+ * is absent (older server).
+ */
+export declare function observe(headers: Headers | undefined | null): void;
+/**
+ * Hit /api/version with If-None-Match (cheap when nothing changed —
+ * 304 with no body). On any change, emit a typed delta.
+ */
+export declare function fetchProbe(): Promise<void>;
+/**
+ * Subscribe to drift events. Called once from useVersionWatcher; the
+ * subscriber renders the UpdatePrompt (toast or silent invalidation).
+ */
+export declare function subscribe(cb: VersionDeltaListener): () => void;
+/**
+ * Test-only: reset internal state. Not exposed via package exports.
+ */
+export declare function __resetForTests(): void;

package/dist-lib/stores/appearance.d.ts

@@ -4,6 +4,7 @@ export type Density = "compact" | "comfortable" | "cozy";
 export type SidebarMode = "wide" | "collapsed";
 export type TabsPosition = "top" | "bottom";
 export type AiSurface = "command" | "panel" | "both" | "off";
+export type FaviconSource = "google" | "direct" | "none";
 export interface Appearance {
     theme: ThemeId;
     accent: AccentId;
@@ -16,6 +17,8 @@ export interface Appearance {
     radius: number;
     zebra: boolean;
     aiSurface: AiSurface;
+    /** Favicon source for unknown hosts in URL cells. See ui_favicon_source. */
+    faviconSource: FaviconSource;
 }
 export declare function applyAppearance(a: Appearance): void;
 interface AppearanceState extends Appearance {

package/dist-lib/types/api.d.ts

@@ -1,4 +1,5 @@
 import type { AccentDef, LocalizedString } from "./schema";
+import type { HydratedFile } from "./files";
 export interface ListMeta {
     total: number;
     page: number;
@@ -47,9 +48,26 @@ export interface AuthUser {
     roles: string[];
     permissions?: string[];
     tenant?: Tenant;
+    /** Populated only when the request is acting under an impersonation session. */
+    impersonation?: ImpersonationInfo;
     created_at: string;
     updated_at: string;
 }
+/**
+ * ImpersonationInfo is the read-side projection of the active session
+ * surfaced by auth.me. Drives the banner, topbar chip, viewport frame,
+ * and the "Exit impersonation" menu item.
+ */
+export interface ImpersonationInfo {
+    session_id: string;
+    real_user_id: string;
+    real_user_email?: string;
+    target_user_id: string;
+    target_user_email?: string;
+    reason: string;
+    started_at: string;
+    expires_at: string;
+}
 export interface LoginResponse {
     expires_at: string;
     user: AuthUser;
@@ -81,24 +99,70 @@ export interface PublicParam {
     description?: LocalizedString;
     value: unknown;
 }
+/** Per-app legal/support URL set rendered in the auth-shell footer. */
+export interface PublicLegalLinks {
+    security_url?: string;
+    privacy_url?: string;
+    terms_url?: string;
+    docs_url?: string;
+}
 /** Subset of branding exposed pre-login by /api/params/public. */
 export interface PublicBranding {
     app_name?: string;
     app_logo?: string;
     app_initial?: string;
     accent_color?: string;
+    ai_name?: string;
     wordmark?: string;
     version_label?: string;
+    status_url?: string;
     auth_tagline?: LocalizedString;
     auth_subtagline?: LocalizedString;
     auth_badges?: LocalizedString[];
+    legal_entity?: string;
+    workspace_domain?: string;
+    legal_links?: PublicLegalLinks;
+}
+/**
+ * Deploy-time identity exposed pre-login by /api/params/public so the
+ * auth shell can render real region/build values (no mockup placeholders).
+ * Each field is empty when unconfigured/unset; consumers hide the pill
+ * when the entire block is missing or empty.
+ */
+export interface PublicMeta {
+    version?: string;
+    revision?: string;
+    build_time?: string;
+    region?: string;
 }
 /** Envelope returned by GET /api/params/public. */
 export interface PublicParamsResponse {
     parameters: PublicParam[];
     accents?: Record<string, AccentDef>;
     branding?: PublicBranding;
+    meta?: PublicMeta;
+}
+/**
+ * Wire envelope for GET /api/params/{code}.
+ *
+ * The server always responds with HTTP 200. `found:false` means the
+ * platform has no value for the code (undeclared, restricted-category,
+ * or no value at any resolution layer); the caller substitutes its own
+ * default. `found:true` means `value` is authoritative - even if it is
+ * null/zero (an explicit nil value is a real value, not absence).
+ *
+ * The default never crosses the wire; servers don't track caller
+ * defaults, so two callers with different defaults always see consistent
+ * server state.
+ */
+export interface ParamLookup {
+    code: string;
+    found: boolean;
+    value?: unknown;
+    source?: "object" | "user" | "role" | "tenant" | "env" | "yaml";
+    type?: string;
 }
+/** @deprecated Prefer `ParamLookup`. Retained for callers still inspecting `source`. */
 export interface ResolvedParam {
     code: string;
     name: LocalizedString;
@@ -199,6 +263,7 @@ export type Units = Record<string, string>;
 /** A row enriched with $-prefixed sub-resources (as returned by Get or write responses). */
 export interface EnrichedRow extends Record<string, unknown> {
     $refs?: Refs;
+    $files?: Record<string, HydratedFile | HydratedFile[] | null>;
     $statuses?: V2StatusInstance[];
     $properties?: V2PropertyInstance[];
     $params?: V2ParamInstance[];

package/dist-lib/types/fieldType.d.ts

@@ -0,0 +1,2 @@
+export type FieldType = "uuid" | "string" | "text" | "rich_text" | "int" | "float" | "bool" | "date" | "time" | "timestamp" | "email" | "url" | "phone" | "enum" | "json" | "ref" | "tags" | "multilang" | "multilang_text" | "structure" | "secret" | "password" | "decimal" | "string_array" | "int_array";
+export declare const FIELD_TYPES: readonly FieldType[];

package/dist-lib/types/files.d.ts

@@ -0,0 +1,76 @@
+export type FileFieldMode = "single" | "array" | "named_map" | "rich_text_inline";
+export interface FileFieldDisplay {
+    widget: string;
+    placeholder?: string;
+    crop_on_upload?: boolean;
+    aspect_ratio?: string;
+    focal_point?: boolean;
+    is_listable?: boolean;
+    listable_thumbnail?: string;
+    reorderable?: boolean;
+    bulk_upload?: boolean;
+    bulk_download?: boolean;
+    lazy_load?: boolean;
+}
+export interface FileNamedSlotDef {
+    accepts?: string[];
+    max_size_bytes?: number;
+    svg_sanitize?: boolean;
+    pdf_strip_js?: boolean;
+    exif_strip?: boolean;
+    aspect_ratio?: string;
+    storage_backend?: string;
+}
+export interface FileFieldDef {
+    name: string;
+    mode: FileFieldMode;
+    accepts?: string[];
+    max_size_bytes?: number;
+    max_count?: number;
+    max_total_size_bytes?: number;
+    required?: boolean;
+    slots?: Record<string, FileNamedSlotDef>;
+    display?: FileFieldDisplay;
+}
+export interface HydratedFile {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    sha256?: string;
+    width?: number;
+    height?: number;
+    page_count?: number;
+    uploaded_at?: string;
+    uploaded_by?: string;
+    url?: string;
+    presigned_url?: string;
+    derivations?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+    position?: number;
+    slot?: string;
+    version?: {
+        number?: number;
+        is_current?: boolean;
+        supersedes_file_id?: string;
+    };
+}
+export type NamedFileFieldValue = Record<string, HydratedFile | null>;
+export type FileFieldValue = HydratedFile | HydratedFile[] | NamedFileFieldValue | null;
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+    pct: number;
+}
+export interface UploadedFile {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    sha256: string;
+    dedup?: boolean;
+    width?: number;
+    height?: number;
+    url?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist-lib/types/schema.d.ts

@@ -1,6 +1,19 @@
 import { OrderedMap } from "./ordmap";
+import type { FileFieldDef } from "./files";
 export { OrderedMap };
 export type LocalizedString = Record<string, string>;
+/**
+ * Per-entity empty-state copy declared in the manifest under
+ * `display.empty_state`. Title and Body are localized; LearnMoreURL is a
+ * plain string. The SDK falls back to a generic "No <plural> yet" derived
+ * from `display.name_plural` when this is absent. Read-only entities never
+ * render the legacy "Create your first..." copy regardless of EmptyStateDef.
+ */
+export interface EmptyStateDef {
+    title?: LocalizedString;
+    body?: LocalizedString;
+    learn_more_url?: string;
+}
 /**
  * Reserved sentinel value for Screen.detail_screen (list screens). Disables
  * row-click navigation even when the entity declares a canonical detail. Paired
@@ -8,6 +21,12 @@ export type LocalizedString = Record<string, string>;
  */
 export declare const DETAIL_SCREEN_NONE = "none";
 export declare function loc(ls: LocalizedString | undefined, lang?: string): string;
+export declare const DISPLAY_KEY = "$display";
+export declare function getDisplayValue(row: Record<string, unknown> | null | undefined, entity: {
+    display?: {
+        display_field?: string;
+    };
+} | null | undefined): string | undefined;
 export declare function fieldDisplayName(field: EntityField, fieldName: string, entities?: Record<string, Entity>): string;
 export interface RefDisplay {
     field: string;
@@ -39,12 +58,22 @@ export interface EntityField {
     default?: unknown;
     display?: {
         name: LocalizedString;
+        description?: LocalizedString;
         width?: number;
         widget?: string;
         is_listable?: boolean;
         is_filterable?: boolean;
         ref_display_field?: string;
         span?: number | "full";
+        bool_labels?: {
+            true: LocalizedString;
+            false: LocalizedString;
+        };
+        value_map?: Record<string, {
+            label?: LocalizedString;
+            color?: string;
+        }>;
+        currency?: string;
     };
     values?: Array<{
         code: string;
@@ -53,6 +82,7 @@ export interface EntityField {
         color?: string;
     }>;
     enum?: string;
+    files?: FileFieldDef;
     ref?: RefConfig;
     structure?: string;
     array?: boolean;
@@ -183,6 +213,8 @@ export interface Entity {
         description?: LocalizedString;
         icon: string;
         display_field?: string;
+        display_template?: string;
+        empty_state?: EmptyStateDef;
     };
     fields: OrderedMap<EntityField>;
     soft_delete?: string;
@@ -194,7 +226,34 @@ export interface Entity {
     actions?: Record<string, Action>;
     handlers?: Record<string, HandlerDef>;
     associations?: Record<string, AssociationDef>;
+    files?: OrderedMap<FileFieldDef>;
     detail_screen?: string;
+    /** Standard CSV export gate per docs/plans/2026-05-01-standard-table-export.md.
+     *  Absent block (or absent `enabled`) means export is enabled. Only an
+     *  explicit `enabled: false` opts out, mirroring the Go ExportEnabled()
+     *  helper. Same shape ships on Screen for per-screen overrides. */
+    export?: ExportConfig;
+    /** At most one row visible per caller. Loader requires either a
+     *  caller-bound `prefilter` or `access: self` to back this. Frontend
+     *  routes a singleton entity's detail screen at the screen's declared
+     *  `route:` without a `:id` segment, and skips list-route registration. */
+    singleton?: boolean;
+    /** Server-enforced WHERE applied unconditionally on every read/write
+     *  via server/handlers/data_prefilter.go. Values may be literal scalars
+     *  OR `$caller.*` expressions (`$caller.user_id`, `$caller.tenant_id`)
+     *  resolved at request time. Security boundary, not a UX hint. */
+    prefilter?: Record<string, unknown>;
+    /** Hard entity-wide access gate. `"self"` restricts every read/write
+     *  to rows where the field marked `owner: true` matches the caller's
+     *  user id (chokepoint + with_check). `"platform_admin"` restricts to
+     *  platform owner / superadmin roles. Empty = standard RBAC. */
+    access?: "self" | "platform_admin";
+    /** Whether the entity participates in RBAC permission gating
+     *  (`entity:<code>:<op>` grants). Mirrors engine.Entity.Permissions. */
+    permissions?: boolean;
+}
+export interface ExportConfig {
+    enabled?: boolean;
 }
 export declare function getPrimaryKeyFields(entity: Entity): string[];
 export type PkValues = Record<string, string>;
@@ -301,6 +360,10 @@ export interface Screen {
     inline_edit?: InlineEditConfig;
     column_overrides?: Record<string, ColumnSpec>;
     activity_rail?: ActivityRailConfig;
+    /** Per-screen override for the CSV export gate. Same shape as Entity.export.
+     *  Either gate being false hides the toolbar Export menu and makes the
+     *  POST endpoint return 403 EXPORT_DISABLED. */
+    export?: ExportConfig;
 }
 export interface QuickPeekConfig {
     enabled?: boolean;
@@ -469,6 +532,7 @@ export interface Branding {
     app_logo?: string;
     app_initial?: string;
     accent_color?: string;
+    ai_name?: string;
     wordmark?: string;
     version_label?: string;
     status_url?: string;

package/dist-lib/vite/declarion-glyph.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <!--
+    Declarion mark: angular letter "D" with an embedded "=" in the negative
+    space of the counter. Encodes the product thesis ("this declaration
+    equals this runtime behavior") in the letterform itself. Solid accent
+    purple #5B5BD6 — visible on both light surfaces and the dark brand
+    panel without prefers-color-scheme tricks. Trademark distinctive,
+    scales crisp from favicon (16px) through hero (96px+).
+  -->
+  <path
+    fill-rule="evenodd"
+    fill="#5B5BD6"
+    d="M 6 6 H 42 L 58 22 V 42 L 42 58 H 6 Z M 18 18 V 46 H 38 L 46 38 V 26 L 38 18 Z"
+  />
+  <rect x="22" y="28" width="20" height="3" fill="#5B5BD6"/>
+  <rect x="22" y="33" width="20" height="3" fill="#5B5BD6"/>
+</svg>

package/dist-lib/vite/fingerprint-plugin.d.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from "vite";
+export interface DeclarionFingerprintPluginOptions {
+    /**
+     * Subdirectory of `outDir` to walk. Defaults to "assets" — Vite's
+     * standard hashed-output location. Override only if a consumer has
+     * customized `build.assetsDir`.
+     */
+    assetsDir?: string;
+    /**
+     * Filename of the emitted fingerprint, written next to `index.html`.
+     * Defaults to "bundle-fingerprint.txt". Match this on the server
+     * side (`apps/server/fingerprint.go:readBundleFingerprint`) if you
+     * customize.
+     */
+    filename?: string;
+}
+/**
+ * Vite plugin that emits a single-line `bundle-fingerprint.txt` next
+ * to `index.html` after every production build. The fingerprint is a
+ * SHA-256 over every file in `assetsDir/` — sorted by name, length-
+ * prefixed (`name\x00sha256\x00`) so concatenation is collision-safe.
+ *
+ * The Declarion server reads this file at boot and folds it into the
+ * combined build identity exposed via `X-Declarion-Version` and
+ * `/api/version`. When a consumer redeploys the UI bundle (changed
+ * JS/CSS/assets) the file changes → server fingerprint changes → SDK
+ * detects asset drift → user is prompted to reload to pick up the
+ * new code.
+ *
+ * Why a separate file rather than walking `assetsDir/` from Go at
+ * boot:
+ *   - Eliminates a per-process I/O dependency on bundle layout
+ *     conventions (Vite could change `assetsDir` defaults; the
+ *     plugin is the canonical contract).
+ *   - Computed once at build time, read once at boot — never on the
+ *     hot path.
+ *   - Lets the consumer image ship the fingerprint as an immutable
+ *     artifact rather than re-deriving it at every server start.
+ *
+ * Backward compatible: if a consumer hasn't adopted the plugin yet,
+ * `bundle-fingerprint.txt` is absent at boot, the server logs once
+ * and degrades to binary-only drift detection (still correct — the
+ * binary fingerprint differs across builds anyway). No errors.
+ */
+export declare function declarionFingerprintPlugin(options?: DeclarionFingerprintPluginOptions): Plugin;

package/dist-lib/vite/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @declarion/react/vite — Vite plugin entry point.
+ *
+ * Separate from the SDK's main React entry (`@declarion/react`) so this
+ * Node-only code never accidentally pulls into a browser bundle.
+ *
+ * Usage in a consumer's `vite.config.ts`:
+ *
+ *     import { declarionFingerprintPlugin } from "@declarion/react/vite";
+ *
+ *     export default defineConfig({
+ *       plugins: [react(), declarionFingerprintPlugin()],
+ *     });
+ *
+ * One line, one plugin — works in every Declarion deployment mode
+ * (local-up, prebuilt-declarion, fully-prebuilt prod) because the
+ * plugin runs at consumer-build time regardless of where the SDK
+ * itself comes from (npm pin / vite alias / link).
+ */
+export { declarionFingerprintPlugin } from "./fingerprint-plugin";
+export type { DeclarionFingerprintPluginOptions } from "./fingerprint-plugin";

package/dist-lib/vite/index.js

@@ -0,0 +1,52 @@
+import { createHash as e } from "node:crypto";
+import { readFileSync as t, readdirSync as n, statSync as r, writeFileSync as i } from "node:fs";
+import { join as a } from "node:path";
+//#region src/vite/fingerprint-plugin.ts
+function o(n = {}) {
+	let r = n.filename ?? "bundle-fingerprint.txt";
+	return {
+		name: "declarion-fingerprint",
+		apply: "build",
+		closeBundle: {
+			sequential: !0,
+			handler() {
+				let o = this.environment.config, c = o.build.outDir, l = a(c, n.assetsDir ?? o.build.assetsDir ?? "assets"), u = s(l);
+				u.sort();
+				let d = e("sha256");
+				for (let n of u) {
+					let r = a(l, n), i = e("sha256").update(t(r)).digest("hex");
+					d.update(`${n.length}:${n}\n`), d.update(`${i.length}:${i}\n`);
+				}
+				let f = d.digest("hex");
+				i(a(c, r), f + "\n", "utf8");
+			}
+		}
+	};
+}
+function s(e) {
+	let t = [], i = [{
+		abs: e,
+		rel: ""
+	}];
+	for (; i.length > 0;) {
+		let { abs: e, rel: o } = i.pop(), s;
+		try {
+			s = n(e);
+		} catch (e) {
+			if (e && typeof e == "object" && "code" in e && e.code === "ENOENT") return [];
+			throw e;
+		}
+		for (let n of s) {
+			let s = a(e, n), c = o ? `${o}/${n}` : n;
+			r(s).isDirectory() ? i.push({
+				abs: s,
+				rel: c
+			}) : t.push(c);
+		}
+	}
+	return t;
+}
+//#endregion
+export { o as declarionFingerprintPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist-lib/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/vite/fingerprint-plugin.ts"],"sourcesContent":["import type { Plugin } from \"vite\";\nimport { createHash } from \"node:crypto\";\nimport {\n  readdirSync,\n  readFileSync,\n  statSync,\n  writeFileSync,\n} from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport interface DeclarionFingerprintPluginOptions {\n  /**\n   * Subdirectory of `outDir` to walk. Defaults to \"assets\" — Vite's\n   * standard hashed-output location. Override only if a consumer has\n   * customized `build.assetsDir`.\n   */\n  assetsDir?: string;\n\n  /**\n   * Filename of the emitted fingerprint, written next to `index.html`.\n   * Defaults to \"bundle-fingerprint.txt\". Match this on the server\n   * side (`apps/server/fingerprint.go:readBundleFingerprint`) if you\n   * customize.\n   */\n  filename?: string;\n}\n\n/**\n * Vite plugin that emits a single-line `bundle-fingerprint.txt` next\n * to `index.html` after every production build. The fingerprint is a\n * SHA-256 over every file in `assetsDir/` — sorted by name, length-\n * prefixed (`name\\x00sha256\\x00`) so concatenation is collision-safe.\n *\n * The Declarion server reads this file at boot and folds it into the\n * combined build identity exposed via `X-Declarion-Version` and\n * `/api/version`. When a consumer redeploys the UI bundle (changed\n * JS/CSS/assets) the file changes → server fingerprint changes → SDK\n * detects asset drift → user is prompted to reload to pick up the\n * new code.\n *\n * Why a separate file rather than walking `assetsDir/` from Go at\n * boot:\n *   - Eliminates a per-process I/O dependency on bundle layout\n *     conventions (Vite could change `assetsDir` defaults; the\n *     plugin is the canonical contract).\n *   - Computed once at build time, read once at boot — never on the\n *     hot path.\n *   - Lets the consumer image ship the fingerprint as an immutable\n *     artifact rather than re-deriving it at every server start.\n *\n * Backward compatible: if a consumer hasn't adopted the plugin yet,\n * `bundle-fingerprint.txt` is absent at boot, the server logs once\n * and degrades to binary-only drift detection (still correct — the\n * binary fingerprint differs across builds anyway). No errors.\n */\nexport function declarionFingerprintPlugin(\n  options: DeclarionFingerprintPluginOptions = {},\n): Plugin {\n  const filename = options.filename ?? \"bundle-fingerprint.txt\";\n\n  return {\n    name: \"declarion-fingerprint\",\n    apply: \"build\",\n    closeBundle: {\n      // `sequential: true` is the safe default — run after rollup has\n      // finished writing the bundle, before any other closeBundle\n      // hooks observe the output dir.\n      sequential: true,\n      handler() {\n        // Read outDir + assetsDir from the resolved Vite config. We\n        // don't capture them in a `configResolved` hook because\n        // `closeBundle` already runs after config resolution.\n        const cfg = this.environment.config;\n        const outDir = cfg.build.outDir;\n        const assetsDir = options.assetsDir ?? cfg.build.assetsDir ?? \"assets\";\n        const assetsRoot = join(outDir, assetsDir);\n\n        const files = collectFiles(assetsRoot);\n        files.sort(); // deterministic order\n\n        const h = createHash(\"sha256\");\n        for (const relPath of files) {\n          const abs = join(assetsRoot, relPath);\n          const fileHash = createHash(\"sha256\")\n            .update(readFileSync(abs))\n            .digest(\"hex\");\n          // Length-prefix discipline — same as the Go side\n          // (store/migrations.go:215-282 + apps/server/fingerprint.go).\n          // `a`+`bc` and `ab`+`c` must produce different hashes.\n          h.update(`${relPath.length}:${relPath}\\n`);\n          h.update(`${fileHash.length}:${fileHash}\\n`);\n        }\n        const combined = h.digest(\"hex\");\n\n        writeFileSync(join(outDir, filename), combined + \"\\n\", \"utf8\");\n      },\n    },\n  };\n}\n\n/**\n * Walks `root` recursively and returns POSIX-style relative paths of\n * every regular file. Sorted by the caller. Symlinks are followed\n * since Vite output dirs don't contain them in practice.\n */\nfunction collectFiles(root: string): string[] {\n  const out: string[] = [];\n  const stack: { abs: string; rel: string }[] = [{ abs: root, rel: \"\" }];\n  while (stack.length > 0) {\n    const { abs, rel } = stack.pop()!;\n    let entries: string[];\n    try {\n      entries = readdirSync(abs);\n    } catch (err) {\n      // Missing assetsDir: nothing to fingerprint. Return empty;\n      // the plugin still emits the file so the server boot path\n      // doesn't have to special-case missing-yet-defined assets.\n      if (\n        err &&\n        typeof err === \"object\" &&\n        \"code\" in err &&\n        (err as { code: string }).code === \"ENOENT\"\n      ) {\n        return [];\n      }\n      throw err;\n    }\n    for (const name of entries) {\n      const childAbs = join(abs, name);\n      const childRel = rel ? `${rel}/${name}` : name;\n      if (statSync(childAbs).isDirectory()) {\n        stack.push({ abs: childAbs, rel: childRel });\n      } else {\n        out.push(childRel);\n      }\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;AAuDA,SAAgB,EACd,IAA6C,EAAE,EACvC;CACR,IAAM,IAAW,EAAQ,YAAY;AAErC,QAAO;EACL,MAAM;EACN,OAAO;EACP,aAAa;GAIX,YAAY;GACZ,UAAU;IAIR,IAAM,IAAM,KAAK,YAAY,QACvB,IAAS,EAAI,MAAM,QAEnB,IAAa,EAAK,GADN,EAAQ,aAAa,EAAI,MAAM,aAAa,SACpB,EAEpC,IAAQ,EAAa,EAAW;AACtC,MAAM,MAAM;IAEZ,IAAM,IAAI,EAAW,SAAS;AAC9B,SAAK,IAAM,KAAW,GAAO;KAC3B,IAAM,IAAM,EAAK,GAAY,EAAQ,EAC/B,IAAW,EAAW,SAAS,CAClC,OAAO,EAAa,EAAI,CAAC,CACzB,OAAO,MAAM;AAKhB,KADA,EAAE,OAAO,GAAG,EAAQ,OAAO,GAAG,EAAQ,IAAI,EAC1C,EAAE,OAAO,GAAG,EAAS,OAAO,GAAG,EAAS,IAAI;;IAE9C,IAAM,IAAW,EAAE,OAAO,MAAM;AAEhC,MAAc,EAAK,GAAQ,EAAS,EAAE,IAAW,MAAM,OAAO;;GAEjE;EACF;;AAQH,SAAS,EAAa,GAAwB;CAC5C,IAAM,IAAgB,EAAE,EAClB,IAAwC,CAAC;EAAE,KAAK;EAAM,KAAK;EAAI,CAAC;AACtE,QAAO,EAAM,SAAS,IAAG;EACvB,IAAM,EAAE,QAAK,WAAQ,EAAM,KAAK,EAC5B;AACJ,MAAI;AACF,OAAU,EAAY,EAAI;WACnB,GAAK;AAIZ,OACE,KACA,OAAO,KAAQ,YACf,UAAU,KACT,EAAyB,SAAS,SAEnC,QAAO,EAAE;AAEX,SAAM;;AAER,OAAK,IAAM,KAAQ,GAAS;GAC1B,IAAM,IAAW,EAAK,GAAK,EAAK,EAC1B,IAAW,IAAM,GAAG,EAAI,GAAG,MAAS;AAC1C,GAAI,EAAS,EAAS,CAAC,aAAa,GAClC,EAAM,KAAK;IAAE,KAAK;IAAU,KAAK;IAAU,CAAC,GAE5C,EAAI,KAAK,EAAS;;;AAIxB,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.1.65",
+  "version": "0.1.68",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",
@@ -15,6 +15,11 @@
       "import": "./dist-lib/index.js",
       "default": "./dist-lib/index.js"
     },
+    "./vite": {
+      "types": "./dist-lib/vite/index.d.ts",
+      "import": "./dist-lib/vite/index.js",
+      "default": "./dist-lib/vite/index.js"
+    },
     "./styles.css": "./dist-lib/declarion-react.css"
   },
   "files": [
@@ -67,6 +72,8 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.2.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^29.0.1",
     "msw": "^2.13.4",
     "react": "^19.0.0",
@@ -74,14 +81,15 @@
     "tailwindcss": "^4.2.4",
     "tsc-alias": "^1.8.16",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.0",
     "vite": "^8.0.9",
     "vitest": "^4.1.5"
   },
   "scripts": {
     "dev": "vite",
-    "build": "tsc --noEmit && vite build",
-    "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json && tsc-alias -p tsconfig.lib.json",
-    "lint": "tsc --noEmit",
+    "build": "tsc -p tsconfig.app.json --noEmit && vite build",
+    "build:lib": "vite build --config vite.lib.config.ts && vite build --config vite.plugin.config.ts && tsc -p tsconfig.lib.json && tsc-alias -p tsconfig.lib.json",
+    "lint": "tsc --noEmit && eslint src",
     "test": "vitest run",
     "preview": "vite preview"
   }