@locode2/harness 0.1.0-preview.1

package/bundled-plugins/fast-frontend/runtimes/antd-admin/src/sdk/index.ts

@@ -0,0 +1,1028 @@
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ComponentType,
+  type CSSProperties,
+  type Dispatch,
+  type Key,
+  type LazyExoticComponent,
+  type PropsWithChildren,
+  type ReactNode,
+  type SetStateAction,
+} from "react";
+import {
+  Button,
+  Card,
+  Col,
+  Drawer,
+  Form,
+  Row,
+  Space,
+  Statistic,
+  Table,
+  Tag,
+  Typography,
+  type CardProps,
+  type DrawerProps,
+  type FormInstance,
+  type FormProps,
+  type RowProps,
+  type StatisticProps,
+  type TableProps,
+  type TagProps,
+} from "antd";
+
+export interface FrontendAppTheme {
+  readonly colorPrimary?: string;
+  readonly borderRadius?: number;
+  readonly compact?: boolean;
+}
+
+/** Business-owned values loaded from `src/app.json`. */
+export interface FrontendBusinessAppManifest {
+  readonly name?: string;
+  /** Project-relative URL below `./generated/`; remote URLs are forbidden. */
+  readonly logo?: string;
+  readonly theme?: FrontendAppTheme;
+}
+
+/** Business-owned values loaded from each page's sibling `route.json`. */
+export interface FrontendRouteMetadata {
+  readonly id: string;
+  readonly path: string;
+  readonly title: string;
+  readonly icon?: string;
+  readonly order?: number;
+  readonly parentId?: string;
+  readonly hidden?: boolean;
+}
+
+export type FrontendPageComponent = ComponentType<Record<string, never>>;
+export type FrontendLazyPageComponent = LazyExoticComponent<FrontendPageComponent>;
+export type FrontendRuntimeProvider = ComponentType<PropsWithChildren>;
+
+export interface FrontendBusinessRoute {
+  readonly metadata: FrontendRouteMetadata;
+  readonly Component: FrontendLazyPageComponent;
+}
+
+export interface FrontendRuntimeApi {
+  readonly app: FrontendBusinessAppManifest;
+  readonly routes: readonly FrontendRouteMetadata[];
+  readonly currentPath: string;
+  navigate(to: string): void;
+}
+
+/**
+ * Synchronous, browser-compatible storage exposed by the Runtime.
+ *
+ * The preview iframe intentionally has an opaque origin, so accessing the
+ * browser's native Storage object may throw. In Harness it transparently uses
+ * a narrowly scoped parent-page bridge; outside Harness it safely falls back
+ * to memory when native storage is unavailable.
+ */
+export interface FrontendStorage {
+  readonly length: number;
+  clear(): void;
+  getItem(key: string): string | null;
+  key(index: number): string | null;
+  removeItem(key: string): void;
+  setItem(key: string, value: string): void;
+}
+
+const STORAGE_PREFIX = "__harness_frontend_runtime__";
+const STORAGE_BRIDGE_VERSION = 1 as const;
+const STORAGE_BRIDGE_READY = "harness.runtime-storage.ready";
+const STORAGE_BRIDGE_INITIALIZE = "harness.runtime-storage.initialize";
+const STORAGE_BRIDGE_MUTATION = "harness.runtime-storage.mutation";
+const STORAGE_BRIDGE_MAX_NAMESPACE_BYTES = 128;
+const STORAGE_BRIDGE_MAX_KEY_BYTES = 512;
+const STORAGE_BRIDGE_MAX_VALUE_BYTES = 256 * 1024;
+const STORAGE_BRIDGE_MAX_ENTRIES = 512;
+const STORAGE_BRIDGE_MAX_TOTAL_BYTES = 1024 * 1024;
+
+type FrontendStorageMutation =
+  | { readonly operation: "set"; readonly key: string; readonly value: string }
+  | { readonly operation: "remove"; readonly key: string }
+  | { readonly operation: "clear" };
+
+interface BridgeStorageAdapter {
+  hydrateFromBridge(values: ReadonlyMap<string, string>): void;
+}
+
+function bridgeByteLength(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function isBridgeRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parseBridgeNamespaces(value: unknown): ReadonlyMap<string, ReadonlyMap<string, string>> | undefined {
+  if (!isBridgeRecord(value)) return undefined;
+  const namespaces = new Map<string, ReadonlyMap<string, string>>();
+  let entryCount = 0;
+  let totalBytes = 0;
+  for (const [namespace, rawValues] of Object.entries(value)) {
+    const namespaceBytes = bridgeByteLength(namespace);
+    if (namespaceBytes === 0 || namespaceBytes > STORAGE_BRIDGE_MAX_NAMESPACE_BYTES || !isBridgeRecord(rawValues)) return undefined;
+    const values = new Map<string, string>();
+    for (const [key, rawValue] of Object.entries(rawValues)) {
+      const keyBytes = bridgeByteLength(key);
+      if (typeof rawValue !== "string" || keyBytes === 0 || keyBytes > STORAGE_BRIDGE_MAX_KEY_BYTES) return undefined;
+      const valueBytes = bridgeByteLength(rawValue);
+      if (valueBytes > STORAGE_BRIDGE_MAX_VALUE_BYTES) return undefined;
+      entryCount += 1;
+      totalBytes += namespaceBytes + keyBytes + valueBytes;
+      if (entryCount > STORAGE_BRIDGE_MAX_ENTRIES || totalBytes > STORAGE_BRIDGE_MAX_TOTAL_BYTES) return undefined;
+      values.set(key, rawValue);
+    }
+    namespaces.set(namespace, values);
+  }
+  return namespaces;
+}
+
+class RuntimeStorageBridgeClient {
+  readonly #parentWindow: Window | undefined;
+  readonly #adapters = new Map<string, Set<BridgeStorageAdapter>>();
+  #channelId: string | undefined;
+  #namespaces: ReadonlyMap<string, ReadonlyMap<string, string>> | undefined;
+  #requestSequence = 0;
+
+  constructor() {
+    if (typeof window === "undefined" || window.parent === window) {
+      this.#parentWindow = undefined;
+      return;
+    }
+    this.#parentWindow = window.parent;
+    window.addEventListener("message", this.#handleMessage);
+    this.#post({ type: STORAGE_BRIDGE_READY, version: STORAGE_BRIDGE_VERSION });
+  }
+
+  get available(): boolean {
+    return this.#parentWindow !== undefined;
+  }
+
+  register(namespace: string, adapter: BridgeStorageAdapter): void {
+    const adapters = this.#adapters.get(namespace) ?? new Set<BridgeStorageAdapter>();
+    adapters.add(adapter);
+    this.#adapters.set(namespace, adapters);
+    const values = this.#namespaces?.get(namespace);
+    if (this.#channelId !== undefined && this.#namespaces !== undefined) {
+      adapter.hydrateFromBridge(values ?? new Map());
+    }
+  }
+
+  mutate(namespace: string, mutation: FrontendStorageMutation): void {
+    if (this.#channelId === undefined) return;
+    this.#requestSequence += 1;
+    this.#post({
+      type: STORAGE_BRIDGE_MUTATION,
+      version: STORAGE_BRIDGE_VERSION,
+      channelId: this.#channelId,
+      requestId: `${Date.now().toString(36)}-${this.#requestSequence.toString(36)}`,
+      namespace,
+      ...mutation,
+    });
+  }
+
+  readonly #handleMessage = (event: MessageEvent<unknown>): void => {
+    if (event.source !== this.#parentWindow || !isBridgeRecord(event.data)) return;
+    if (event.data.type !== STORAGE_BRIDGE_INITIALIZE || event.data.version !== STORAGE_BRIDGE_VERSION) return;
+    const channelId = event.data.channelId;
+    if (typeof channelId !== "string" || bridgeByteLength(channelId) === 0 || bridgeByteLength(channelId) > 128) return;
+    if (this.#channelId !== undefined) return;
+    const namespaces = parseBridgeNamespaces(event.data.namespaces);
+    if (namespaces === undefined) return;
+    this.#channelId = channelId;
+    this.#namespaces = namespaces;
+    for (const [namespace, adapters] of this.#adapters) {
+      const values = namespaces.get(namespace) ?? new Map<string, string>();
+      for (const adapter of adapters) adapter.hydrateFromBridge(values);
+    }
+  };
+
+  #post(message: Record<string, unknown>): void {
+    try {
+      // The child has an opaque origin and cannot derive a stable parent
+      // targetOrigin. The parent validates this exact WindowProxy and a random
+      // channel before accepting any mutation.
+      this.#parentWindow?.postMessage(message, "*");
+    } catch {
+      // Standalone exports and disappearing parent windows remain usable.
+    }
+  }
+}
+
+const runtimeStorageBridge = new RuntimeStorageBridgeClient();
+const storageAdapters = new Map<string, SafeFrontendStorage>();
+
+class SafeFrontendStorage implements FrontendStorage, BridgeStorageAdapter {
+  readonly #memory = new Map<string, string>();
+  readonly #prefix: string;
+  readonly #namespace: string;
+  readonly #readyListeners = new Set<() => void>();
+  readonly #pendingMutations: FrontendStorageMutation[] = [];
+  #persistent: Storage | undefined;
+  #ready = true;
+
+  constructor(namespace: string) {
+    this.#namespace = namespace;
+    this.#prefix = `${STORAGE_PREFIX}:${encodeURIComponent(namespace)}:`;
+    try {
+      // Accessing this property itself throws in a sandboxed opaque-origin
+      // iframe. Keep it inside the same safety boundary as all Storage calls.
+      this.#persistent = globalThis.localStorage;
+      if (this.#persistent !== undefined) this.#hydrateFromPersistentStorage();
+      else this.#enableBridge();
+    } catch {
+      this.#persistent = undefined;
+      this.#enableBridge();
+    }
+  }
+
+  get ready(): boolean {
+    return this.#ready;
+  }
+
+  onReady(listener: () => void): () => void {
+    if (this.#ready) {
+      listener();
+      return () => undefined;
+    }
+    this.#readyListeners.add(listener);
+    return () => { this.#readyListeners.delete(listener); };
+  }
+
+  hydrateFromBridge(values: ReadonlyMap<string, string>): void {
+    this.#memory.clear();
+    for (const [key, value] of values) this.#memory.set(key, value);
+    this.#ready = true;
+    const pending = this.#pendingMutations.splice(0);
+    for (const mutation of pending) {
+      this.#applyMemoryMutation(mutation);
+      runtimeStorageBridge.mutate(this.#namespace, mutation);
+    }
+    for (const listener of [...this.#readyListeners]) listener();
+    this.#readyListeners.clear();
+  }
+
+  get length(): number {
+    return this.#memory.size;
+  }
+
+  clear(): void {
+    const keys = [...this.#memory.keys()];
+    this.#memory.clear();
+    const persistent = this.#persistent;
+    if (persistent === undefined) {
+      this.#bridgeMutation({ operation: "clear" });
+      return;
+    }
+    try {
+      for (const key of keys) persistent.removeItem(this.#storageKey(key));
+    } catch {
+      this.#persistent = undefined;
+      this.#enableBridge({ operation: "clear" });
+    }
+  }
+
+  getItem(key: string): string | null {
+    const normalizedKey = String(key);
+    const persistent = this.#persistent;
+    if (persistent !== undefined) {
+      try {
+        const value = persistent.getItem(this.#storageKey(normalizedKey));
+        if (value === null) this.#memory.delete(normalizedKey);
+        else this.#memory.set(normalizedKey, value);
+        return value;
+      } catch {
+        this.#persistent = undefined;
+        this.#enableBridge();
+      }
+    }
+    return this.#memory.get(normalizedKey) ?? null;
+  }
+
+  key(index: number): string | null {
+    if (!Number.isInteger(index) || index < 0) return null;
+    return [...this.#memory.keys()][index] ?? null;
+  }
+
+  removeItem(key: string): void {
+    const normalizedKey = String(key);
+    this.#memory.delete(normalizedKey);
+    const persistent = this.#persistent;
+    const mutation = { operation: "remove", key: normalizedKey } as const;
+    if (persistent === undefined) {
+      this.#bridgeMutation(mutation);
+      return;
+    }
+    try {
+      persistent.removeItem(this.#storageKey(normalizedKey));
+    } catch {
+      this.#persistent = undefined;
+      this.#enableBridge(mutation);
+    }
+  }
+
+  setItem(key: string, value: string): void {
+    const normalizedKey = String(key);
+    const normalizedValue = String(value);
+    // Mirror first so a quota/security failure cannot lose the current write.
+    this.#memory.set(normalizedKey, normalizedValue);
+    const persistent = this.#persistent;
+    const mutation = { operation: "set", key: normalizedKey, value: normalizedValue } as const;
+    if (persistent === undefined) {
+      this.#bridgeMutation(mutation);
+      return;
+    }
+    try {
+      persistent.setItem(this.#storageKey(normalizedKey), normalizedValue);
+    } catch {
+      this.#persistent = undefined;
+      this.#enableBridge(mutation);
+    }
+  }
+
+  #hydrateFromPersistentStorage(): void {
+    const persistent = this.#persistent;
+    if (persistent === undefined) return;
+    for (let index = 0; index < persistent.length; index += 1) {
+      const storedKey = persistent.key(index);
+      if (storedKey === null || !storedKey.startsWith(this.#prefix)) continue;
+      const value = persistent.getItem(storedKey);
+      if (value !== null) this.#memory.set(storedKey.slice(this.#prefix.length), value);
+    }
+  }
+
+  #storageKey(key: string): string {
+    return `${this.#prefix}${key}`;
+  }
+
+  #enableBridge(pending?: FrontendStorageMutation): void {
+    if (!runtimeStorageBridge.available) return;
+    if (pending !== undefined) this.#pendingMutations.push(pending);
+    if (!this.#ready) return;
+    this.#ready = false;
+    runtimeStorageBridge.register(this.#namespace, this);
+  }
+
+  #bridgeMutation(mutation: FrontendStorageMutation): void {
+    if (!runtimeStorageBridge.available) return;
+    if (!this.#ready) {
+      this.#pendingMutations.push(mutation);
+      return;
+    }
+    runtimeStorageBridge.mutate(this.#namespace, mutation);
+  }
+
+  #applyMemoryMutation(mutation: FrontendStorageMutation): void {
+    if (mutation.operation === "clear") {
+      this.#memory.clear();
+    } else if (mutation.operation === "remove") {
+      this.#memory.delete(mutation.key);
+    } else {
+      this.#memory.set(mutation.key, mutation.value);
+    }
+  }
+}
+
+/**
+ * Returns a synchronous application storage adapter isolated by namespace.
+ * Native localStorage is used when available. Harness previews use the scoped
+ * parent bridge after an access failure; standalone restricted environments
+ * retain an in-memory fallback instead of crashing React.
+ */
+function getFrontendStorageAdapter(namespace = "default"): SafeFrontendStorage {
+  const normalizedNamespace = namespace.trim() || "default";
+  const existing = storageAdapters.get(normalizedNamespace);
+  if (existing !== undefined) return existing;
+  const adapter = new SafeFrontendStorage(normalizedNamespace);
+  storageAdapters.set(normalizedNamespace, adapter);
+  return adapter;
+}
+
+export function getFrontendStorage(namespace = "default"): FrontendStorage {
+  return getFrontendStorageAdapter(namespace);
+}
+
+export type FrontendPageWidth = "standard" | "wide" | "full";
+
+export interface FrontendShellUser {
+  readonly name: ReactNode;
+  readonly description?: ReactNode;
+  readonly avatar?: ReactNode;
+}
+
+export interface FrontendShellOptions {
+  /** Global actions rendered in the Runtime-owned top header. */
+  readonly headerActions?: ReactNode;
+  /** Current business user rendered by the Runtime instead of a page-owned header. */
+  readonly currentUser?: FrontendShellUser;
+  /** A controlled user/role switcher, usually an Ant Design Select. */
+  readonly userSwitcher?: ReactNode;
+}
+
+export interface FrontendPageOptions {
+  /** Runtime-owned page heading. Omit it to reuse the active route title. */
+  readonly title?: ReactNode;
+  readonly description?: ReactNode;
+  /** Actions aligned with the Runtime-owned page title. */
+  readonly titleActions?: ReactNode;
+  readonly width?: FrontendPageWidth;
+}
+
+/** @internal Shared with the immutable Runtime shell. */
+export interface FrontendChromeRegistrationApi {
+  readonly routeKey: string;
+  registerShell(options: FrontendShellOptions): () => void;
+  registerPage(routeKey: string, options: FrontendPageOptions): () => void;
+}
+
+const FrontendChromeContext = createContext<FrontendChromeRegistrationApi | null>(null);
+
+interface FrontendLiveNodeSlot {
+  getSnapshot(): ReactNode;
+  publish(value: ReactNode): void;
+  subscribe(listener: () => void): () => void;
+}
+
+function createFrontendLiveNodeSlot(initialValue: ReactNode): FrontendLiveNodeSlot {
+  let value = initialValue;
+  const listeners = new Set<() => void>();
+  return {
+    getSnapshot: () => value,
+    publish: (nextValue) => {
+      if (Object.is(value, nextValue)) return;
+      value = nextValue;
+      for (const listener of [...listeners]) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => { listeners.delete(listener); };
+    },
+  };
+}
+
+function FrontendLiveNode({ slot }: { readonly slot: FrontendLiveNodeSlot }): ReactNode {
+  return useSyncExternalStore(slot.subscribe, slot.getSnapshot, slot.getSnapshot);
+}
+
+// The Runtime is browser-only, but the SDK contract is also rendered in Node
+// smoke tests. Avoid the useLayoutEffect server warning without delaying slot
+// updates in the real preview.
+const useFrontendLayoutEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * Keeps a chrome slot registered once while independently refreshing its
+ * ReactNode. This is important for inline callbacks: using their identity as an
+ * effect dependency would create a registration/render loop, while ignoring
+ * them would leave the header or page action holding a stale closure.
+ */
+function useFrontendLiveNode(value: ReactNode): ReactNode {
+  const slot = useRef<FrontendLiveNodeSlot | null>(null);
+  if (slot.current === null) slot.current = createFrontendLiveNodeSlot(value);
+  const liveSlot = slot.current;
+  const node = useRef<ReactNode | undefined>(undefined);
+  if (node.current === undefined) {
+    node.current = createElement(FrontendLiveNode, { slot: liveSlot });
+  }
+  useFrontendLayoutEffect(() => {
+    liveSlot.publish(value);
+  }, [liveSlot, value]);
+  return node.current;
+}
+
+/** @internal Runtime-owned provider exported through the singleton SDK module. */
+export function FrontendChromeContextProvider({
+  value,
+  children,
+}: PropsWithChildren<{ readonly value: FrontendChromeRegistrationApi }>): ReactNode {
+  return createElement(FrontendChromeContext.Provider, { value }, children);
+}
+
+/** Register controlled application-wide content in the Runtime-owned header. */
+export function useFrontendShell(options: FrontendShellOptions): void {
+  const chrome = useContext(FrontendChromeContext);
+  const headerActions = useFrontendLiveNode(options.headerActions);
+  const userSwitcher = useFrontendLiveNode(options.userSwitcher);
+  const currentUserName = useFrontendLiveNode(options.currentUser?.name);
+  const currentUserDescription = useFrontendLiveNode(options.currentUser?.description);
+  const currentUserAvatar = useFrontendLiveNode(options.currentUser?.avatar);
+  const hasHeaderActions = options.headerActions !== undefined;
+  const hasUserSwitcher = options.userSwitcher !== undefined;
+  const hasCurrentUser = options.currentUser !== undefined;
+  const hasCurrentUserDescription = options.currentUser?.description !== undefined;
+  const hasCurrentUserAvatar = options.currentUser?.avatar !== undefined;
+
+  useEffect(() => chrome?.registerShell({
+    ...(hasHeaderActions ? { headerActions } : {}),
+    ...(hasUserSwitcher ? { userSwitcher } : {}),
+    ...(hasCurrentUser ? {
+      currentUser: {
+        name: currentUserName,
+        ...(hasCurrentUserDescription ? { description: currentUserDescription } : {}),
+        ...(hasCurrentUserAvatar ? { avatar: currentUserAvatar } : {}),
+      },
+    } : {}),
+  }), [
+    chrome,
+    currentUserAvatar,
+    currentUserDescription,
+    currentUserName,
+    hasCurrentUser,
+    hasCurrentUserAvatar,
+    hasCurrentUserDescription,
+    hasHeaderActions,
+    hasUserSwitcher,
+    headerActions,
+    userSwitcher,
+  ]);
+}
+
+/** Register the current page title, title actions and content width with the Runtime shell. */
+export function useFrontendPage(options: FrontendPageOptions): void {
+  const chrome = useContext(FrontendChromeContext);
+  const title = useFrontendLiveNode(options.title);
+  const description = useFrontendLiveNode(options.description);
+  const titleActions = useFrontendLiveNode(options.titleActions);
+  const hasTitle = options.title !== undefined;
+  const hasDescription = options.description !== undefined;
+  const hasTitleActions = options.titleActions !== undefined;
+  useEffect(
+    () => chrome?.registerPage(chrome.routeKey, {
+      ...(hasTitle ? { title } : {}),
+      ...(hasDescription ? { description } : {}),
+      ...(hasTitleActions ? { titleActions } : {}),
+      ...(options.width === undefined ? {} : { width: options.width }),
+    }),
+    [
+      chrome,
+      description,
+      hasDescription,
+      hasTitle,
+      hasTitleActions,
+      options.width,
+      title,
+      titleActions,
+    ],
+  );
+}
+
+export type FrontendShellProviderProps = PropsWithChildren<FrontendShellOptions>;
+
+/**
+ * Place this in `src/app/providers.tsx` to fill Runtime header slots without
+ * creating a second application Header inside business pages.
+ */
+export function FrontendShellProvider({
+  children,
+  headerActions,
+  currentUser,
+  userSwitcher,
+}: FrontendShellProviderProps): ReactNode {
+  useFrontendShell({ headerActions, currentUser, userSwitcher });
+  return children;
+}
+
+export interface PageContainerProps extends PropsWithChildren<FrontendPageOptions> {
+  readonly className?: string;
+  readonly style?: CSSProperties;
+  readonly "data-harness-source"?: string;
+}
+
+/** Standard business page root whose title and width are owned by the shell. */
+export function PageContainer({
+  children,
+  className,
+  style,
+  title,
+  description,
+  titleActions,
+  width = "wide",
+  "data-harness-source": sourceMarker,
+}: PageContainerProps): ReactNode {
+  useFrontendPage({ title, description, titleActions, width });
+  return createElement("div", {
+    className: ["harness-page-container", className].filter(Boolean).join(" "),
+    style,
+    ...(sourceMarker ? { "data-harness-source": sourceMarker } : {}),
+  }, children);
+}
+
+export interface FrontendMetric {
+  readonly key: Key;
+  readonly title: ReactNode;
+  readonly value: StatisticProps["value"];
+  readonly prefix?: ReactNode;
+  readonly suffix?: ReactNode;
+  readonly precision?: number;
+  readonly valueStyle?: CSSProperties;
+  readonly description?: ReactNode;
+  readonly loading?: boolean;
+}
+
+export interface MetricGridProps {
+  readonly items: readonly FrontendMetric[];
+  readonly columns?: 1 | 2 | 3 | 4 | 6;
+  readonly gutter?: RowProps["gutter"];
+  readonly className?: string;
+  readonly style?: CSSProperties;
+  readonly "data-harness-source"?: string;
+}
+
+/** Responsive Ant Design metric cards with consistent spacing and height. */
+export function MetricGrid({
+  items,
+  columns = 4,
+  gutter = [16, 16],
+  className,
+  style,
+  "data-harness-source": sourceMarker,
+}: MetricGridProps): ReactNode {
+  const largeSpan = 24 / columns;
+  return createElement(Row, {
+    gutter,
+    className: ["harness-runtime-metric-grid", className].filter(Boolean).join(" "),
+    style,
+    ...(sourceMarker ? { "data-harness-source": sourceMarker } : {}),
+  }, items.map((item) => createElement(
+    Col,
+    {
+      key: item.key,
+      xs: 24,
+      sm: columns === 1 ? 24 : 12,
+      lg: largeSpan,
+    },
+    createElement(
+      Card,
+      {
+        loading: item.loading,
+        className: "harness-runtime-metric-card",
+      },
+      createElement(Statistic, {
+        title: item.title,
+        value: item.value,
+        prefix: item.prefix,
+        suffix: item.suffix,
+        precision: item.precision,
+        valueStyle: item.valueStyle,
+      }),
+      item.description === undefined
+        ? null
+        : createElement(
+          Typography.Text,
+          { type: "secondary", className: "harness-runtime-metric-description" },
+          item.description,
+        ),
+    ),
+  )));
+}
+
+export interface DataTableProps<RecordType extends object = Record<string, unknown>>
+  extends Omit<TableProps<RecordType>, "title"> {
+  readonly title?: ReactNode;
+  readonly description?: ReactNode;
+  readonly toolbar?: ReactNode;
+  readonly cardProps?: Omit<CardProps, "children" | "extra" | "title">;
+  readonly "data-harness-source"?: string;
+}
+
+/** Ant Design Table in a consistent responsive toolbar/card shell. */
+export function DataTable<RecordType extends object = Record<string, unknown>>({
+  title,
+  description,
+  toolbar,
+  cardProps,
+  pagination,
+  scroll,
+  size = "middle",
+  "data-harness-source": sourceMarker,
+  ...tableProps
+}: DataTableProps<RecordType>): ReactNode {
+  const heading = title === undefined && description === undefined
+    ? undefined
+    : createElement("div", { className: "harness-runtime-data-table-heading" },
+      title === undefined
+        ? null
+        : createElement(Typography.Title, { level: 5, ellipsis: true }, title),
+      description === undefined
+        ? null
+        : createElement(Typography.Text, { type: "secondary" }, description));
+  const TypedTable = Table<RecordType>;
+  return createElement(Card, {
+    ...cardProps,
+    className: ["harness-runtime-data-table-card", cardProps?.className].filter(Boolean).join(" "),
+    title: heading,
+    extra: toolbar,
+    ...(sourceMarker ? { "data-harness-source": sourceMarker } : {}),
+  }, createElement(TypedTable, {
+    ...tableProps,
+    size,
+    scroll: scroll ?? { x: "max-content" },
+    pagination: pagination === undefined
+      ? { showSizeChanger: true, showTotal: (total) => `共 ${total} 条` }
+      : pagination,
+  }));
+}
+
+export interface CrudDrawerProps<Values extends object = Record<string, unknown>>
+  extends Omit<DrawerProps, "children" | "footer" | "onClose" | "open"> {
+  readonly open: boolean;
+  readonly form?: FormInstance<Values>;
+  readonly formProps?: Omit<FormProps<Values>, "children" | "form" | "initialValues" | "onFinish">;
+  readonly initialValues?: Partial<Values>;
+  readonly children?: ReactNode;
+  readonly submitText?: ReactNode;
+  readonly cancelText?: ReactNode;
+  readonly submitting?: boolean;
+  readonly onClose: () => void;
+  readonly onSubmit: (values: Values) => void | Promise<void>;
+  readonly onSubmitError?: (error: unknown) => void;
+  readonly "data-harness-source"?: string;
+}
+
+/** Controlled CRUD form Drawer with validation, footer and submit state. */
+export function CrudDrawer<Values extends object = Record<string, unknown>>({
+  open,
+  form: providedForm,
+  formProps,
+  initialValues,
+  children,
+  submitText = "保存",
+  cancelText = "取消",
+  submitting,
+  onClose,
+  onSubmit,
+  onSubmitError,
+  width = 520,
+  "data-harness-source": sourceMarker,
+  ...drawerProps
+}: CrudDrawerProps<Values>): ReactNode {
+  const [internalForm] = Form.useForm<Values>();
+  const TypedForm = Form<Values>;
+  const form = providedForm ?? internalForm;
+  const [internalSubmitting, setInternalSubmitting] = useState(false);
+  const isSubmitting = submitting ?? internalSubmitting;
+
+  useEffect(() => {
+    if (!open) return;
+    form.resetFields();
+    if (initialValues !== undefined) form.setFieldsValue(initialValues as Values);
+  }, [form, initialValues, open]);
+
+  const submit = async () => {
+    if (isSubmitting) return;
+    setInternalSubmitting(true);
+    try {
+      const values = await form.validateFields();
+      await onSubmit(values);
+    } catch (error) {
+      onSubmitError?.(error);
+    } finally {
+      setInternalSubmitting(false);
+    }
+  };
+
+  return createElement(Drawer, {
+    ...drawerProps,
+    open,
+    width,
+    onClose,
+    destroyOnHidden: true,
+    ...(sourceMarker ? { "data-harness-source": sourceMarker } : {}),
+    footer: createElement("div", { className: "harness-runtime-crud-drawer-footer" },
+      createElement(Space, null,
+        createElement(Button, { onClick: onClose, disabled: isSubmitting }, cancelText),
+        createElement(Button, {
+          type: "primary",
+          loading: isSubmitting,
+          onClick: () => { void submit(); },
+        }, submitText))),
+  }, createElement(TypedForm, {
+    ...formProps,
+    form,
+    layout: formProps?.layout ?? "vertical",
+    requiredMark: formProps?.requiredMark ?? "optional",
+  }, children));
+}
+
+const DEFAULT_STATUS_COLORS: Readonly<Record<string, TagProps["color"]>> = {
+  "未开始": "default",
+  "待处理": "warning",
+  "待办": "warning",
+  "进行中": "processing",
+  "处理中": "processing",
+  "已完成": "success",
+  "成功": "success",
+  "已关闭": "default",
+  "已取消": "default",
+  "失败": "error",
+  "已逾期": "error",
+};
+
+export interface StatusTagProps extends Omit<TagProps, "children" | "color"> {
+  readonly status: string;
+  readonly label?: ReactNode;
+  readonly color?: TagProps["color"];
+  readonly colors?: Readonly<Record<string, TagProps["color"]>>;
+}
+
+/** Consistent status colors with an explicit per-application override map. */
+export function StatusTag({
+  status,
+  label,
+  color,
+  colors,
+  ...tagProps
+}: StatusTagProps): ReactNode {
+  return createElement(Tag, {
+    ...tagProps,
+    color: color ?? colors?.[status] ?? DEFAULT_STATUS_COLORS[status] ?? "default",
+  }, label ?? status);
+}
+
+export type FrontendStoreSetter<TState> = TState | ((current: TState) => TState);
+export type FrontendStorePatch<TState extends object> = Partial<TState> | ((current: TState) => Partial<TState>);
+
+export interface FrontendStore<TState extends object> {
+  getState(): TState;
+  setState(next: FrontendStoreSetter<TState>): void;
+  update(patch: FrontendStorePatch<TState>): void;
+  reset(): void;
+  subscribe(listener: () => void): () => void;
+  useStore<Selection = TState>(selector?: (state: TState) => Selection): Selection;
+}
+
+/** Small dependency-free external store suitable for shared mock business data. */
+export function createFrontendStore<TState extends object>(
+  initialState: TState | (() => TState),
+): FrontendStore<TState> {
+  const createInitialState = () => typeof initialState === "function"
+    ? (initialState as () => TState)()
+    : initialState;
+  let state = createInitialState();
+  const listeners = new Set<() => void>();
+  const getState = () => state;
+  const subscribe = (listener: () => void) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+  };
+  const setState = (next: FrontendStoreSetter<TState>) => {
+    const value = typeof next === "function"
+      ? (next as (current: TState) => TState)(state)
+      : next;
+    if (Object.is(value, state)) return;
+    state = value;
+    for (const listener of [...listeners]) listener();
+  };
+  const store: FrontendStore<TState> = {
+    getState,
+    setState,
+    update: (patch) => setState((current) => ({
+      ...current,
+      ...(typeof patch === "function" ? patch(current) : patch),
+    })),
+    reset: () => setState(createInitialState()),
+    subscribe,
+    useStore: <Selection = TState>(selector?: (value: TState) => Selection): Selection => {
+      const snapshot = useSyncExternalStore(subscribe, getState, getState);
+      return selector === undefined ? snapshot as unknown as Selection : selector(snapshot);
+    },
+  };
+  return store;
+}
+
+export interface PersistentFrontendStateOptions<T> {
+  readonly namespace?: string;
+  readonly serialize?: (value: T) => string;
+  readonly deserialize?: (value: string) => T;
+}
+
+/** useState-compatible state persisted through the Runtime's safe Storage adapter. */
+export function usePersistentFrontendState<T>(
+  key: string,
+  initialState: T | (() => T),
+  options: PersistentFrontendStateOptions<T> = {},
+): [T, Dispatch<SetStateAction<T>>] {
+  const configuration = useRef<{
+    readonly storage: SafeFrontendStorage;
+    readonly key: string;
+    readonly serialize: (value: T) => string;
+    readonly deserialize: (value: string) => T;
+  } | null>(null);
+  let config = configuration.current;
+  if (config === null) {
+    config = {
+      storage: getFrontendStorageAdapter(options.namespace),
+      key,
+      serialize: options.serialize ?? ((value) => JSON.stringify(value) ?? "null"),
+      deserialize: options.deserialize ?? ((value) => JSON.parse(value) as T),
+    };
+    configuration.current = config;
+  }
+  const hydrated = useRef(config.storage.ready);
+  const changedBeforeHydration = useRef(false);
+  const skipPersistenceOnce = useRef(false);
+  const [state, setState] = useState<T>(() => {
+    const stored = config.storage.getItem(config.key);
+    if (stored !== null) {
+      try {
+        return config.deserialize(stored);
+      } catch {
+        // Invalid or outdated data falls back to the caller's safe default.
+      }
+    }
+    return typeof initialState === "function" ? (initialState as () => T)() : initialState;
+  });
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const setPersistentState = useCallback<Dispatch<SetStateAction<T>>>((next) => {
+    if (!hydrated.current) changedBeforeHydration.current = true;
+    const value = typeof next === "function"
+      ? (next as (current: T) => T)(stateRef.current)
+      : next;
+    stateRef.current = value;
+    setState(value);
+  }, []);
+
+  useEffect(() => {
+    if (hydrated.current) return;
+    return config.storage.onReady(() => {
+      if (hydrated.current) return;
+      hydrated.current = true;
+      if (changedBeforeHydration.current) {
+        try {
+          config.storage.setItem(config.key, config.serialize(stateRef.current));
+        } catch {
+          // A custom serializer must not crash bridge hydration.
+        }
+        return;
+      }
+      const stored = config.storage.getItem(config.key);
+      if (stored !== null) {
+        try {
+          skipPersistenceOnce.current = true;
+          setState(config.deserialize(stored));
+          return;
+        } catch {
+          skipPersistenceOnce.current = false;
+          // Invalid or outdated data is replaced with the caller's safe default.
+        }
+      }
+      try {
+        config.storage.setItem(config.key, config.serialize(stateRef.current));
+      } catch {
+        // A custom serializer must not crash bridge hydration.
+      }
+    });
+  }, [config]);
+
+  useEffect(() => {
+    if (!hydrated.current) return;
+    if (skipPersistenceOnce.current) {
+      skipPersistenceOnce.current = false;
+      return;
+    }
+    try {
+      config.storage.setItem(config.key, config.serialize(state));
+    } catch {
+      // A custom serializer must not crash the page render lifecycle.
+    }
+  }, [config, state]);
+  return [state, setPersistentState];
+}
+
+const FrontendRuntimeContext = createContext<FrontendRuntimeApi | null>(null);
+
+/** Runtime-internal provider exported through the same singleton SDK module. */
+export function FrontendRuntimeContextProvider({
+  value,
+  children,
+}: PropsWithChildren<{ readonly value: FrontendRuntimeApi }>): ReactNode {
+  return createElement(FrontendRuntimeContext.Provider, { value }, children);
+}
+
+/** Access app metadata and navigate without depending on Runtime internals. */
+export function useFrontendRuntime(): FrontendRuntimeApi {
+  const value = useContext(FrontendRuntimeContext);
+  if (value === null) {
+    throw new Error("useFrontendRuntime must be used inside the Harness frontend runtime");
+  }
+  return value;
+}
+
+/** Type-safe identity helper for business provider modules. */
+export function defineFrontendProviders(
+  providers: readonly FrontendRuntimeProvider[],
+): readonly FrontendRuntimeProvider[] {
+  return providers;
+}