Skip to content

The Open Standard for Generative UI

Mint a __libraryId on createLibrary and echo it on stream events. (#1019)

ABa7ac9055d850
diff --git a/packages/lang-core/src/__tests__/library.test.ts b/packages/lang-core/src/__tests__/library.test.ts
index fbdbf617b..046f76f7e 100644
--- a/packages/lang-core/src/__tests__/library.test.ts
+++ b/packages/lang-core/src/__tests__/library.test.ts
@@ -181,10 +181,14 @@ describe("per-library registry", () => {
});
expect(named.id).toBe("acme-support@3");
expect(named.toSpec().id).toBe("acme-support@3");
+ expect(named.__libraryId).toEqual(expect.any(String));
+ expect(named.__libraryId).not.toBe("acme-support@3");
const anonymous = createLibrary({ components: [Text], root: "TextContent" });
expect(anonymous.id).toBeUndefined();
expect("id" in anonymous.toSpec()).toBe(false);
+ expect(anonymous.__libraryId).toEqual(expect.any(String));
+ expect(anonymous.__libraryId).not.toBe(named.__libraryId);
});
it("toJSONSchema carries defineComponent descriptions on $defs entries", () => {
diff --git a/packages/lang-core/src/library.ts b/packages/lang-core/src/library.ts
index 98af3bfe3..c49848a98 100644
--- a/packages/lang-core/src/library.ts
+++ b/packages/lang-core/src/library.ts
@@ -337,6 +337,8 @@ export interface Library<C = unknown> {
readonly componentGroups: ComponentGroup[] | undefined;
readonly root: string | undefined;
readonly id: string | undefined;
+ /** Instance id minted by `createLibrary()`. Distinct from the optional public `id`. */
+ readonly __libraryId: string;
prompt(options?: PromptOptions): string;
toSpec(): PromptSpec;
@@ -350,12 +352,23 @@ export interface LibraryDefinition<C = unknown> {
id?: string;
}
+let fallbackLibraryId = 0;
+
+function createLibraryId(): string {
+ if (typeof globalThis.crypto?.randomUUID === "function") {
+ return globalThis.crypto.randomUUID();
+ }
+ fallbackLibraryId += 1;
+ return `openui-lib-${Date.now().toString(36)}-${fallbackLibraryId.toString(36)}`;
+}
+
/**
* Create a component library from an array of defined components.
*/
export function createLibrary<C = unknown>(input: LibraryDefinition<C>): Library<C> {
const componentsRecord: Record<string, DefinedComponent<any, C>> = {};
const reg = z.registry<{ id: string }>();
+ const __libraryId = createLibraryId();
for (const comp of input.components) {
reg.add(comp.props as z.$ZodType, { id: comp.name });
@@ -374,6 +387,7 @@ export function createLibrary<C = unknown>(input: LibraryDefinition<C>): Library
componentGroups: input.componentGroups,
root: input.root,
id: input.id,
+ __libraryId,
prompt(options?: PromptOptions): string {
const spec: PromptSpec = {
diff --git a/packages/observability-cloud/src/events/stream.ts b/packages/observability-cloud/src/events/stream.ts
index df504c201..1c14df65e 100644
--- a/packages/observability-cloud/src/events/stream.ts
+++ b/packages/observability-cloud/src/events/stream.ts
@@ -51,6 +51,8 @@ export interface SettledStreamEventDetail {
errors: unknown[];
errorCount: number;
message: string;
+ /** `createLibrary()` instance id for the Renderer that produced this stream. */
+ __libraryId?: string;
}
/** Wire shape for settled stream events sent to cloud ingest. */
diff --git a/packages/react-lang/src/hooks/streamEvent.ts b/packages/react-lang/src/hooks/streamEvent.ts
index 5dd439b4a..547bd0c54 100644
--- a/packages/react-lang/src/hooks/streamEvent.ts
+++ b/packages/react-lang/src/hooks/streamEvent.ts
@@ -31,4 +31,6 @@ export interface SettledStreamEventDetail {
errors: unknown[];
errorCount: number;
message: string;
+ /** `createLibrary()` instance id for the Renderer that produced this stream. */
+ __libraryId?: string;
}
diff --git a/packages/react-lang/src/hooks/useOpenUIState.ts b/packages/react-lang/src/hooks/useOpenUIState.ts
index 9628c65c7..13df4cde6 100644
--- a/packages/react-lang/src/hooks/useOpenUIState.ts
+++ b/packages/react-lang/src/hooks/useOpenUIState.ts
@@ -461,6 +461,7 @@ export function useOpenUIState(
errorsRef,
errorRevision,
publish: publishObservability,
+ __libraryId: library.__libraryId,
});
return { result: evaluatedResult, parseResult: result, contextValue, isQueryLoading };
diff --git a/packages/react-lang/src/hooks/useStreamingObservability.ts b/packages/react-lang/src/hooks/useStreamingObservability.ts
index 8eab5313b..b06c2e109 100644
--- a/packages/react-lang/src/hooks/useStreamingObservability.ts
+++ b/packages/react-lang/src/hooks/useStreamingObservability.ts
@@ -18,6 +18,8 @@ export interface UseStreamingObservabilityOptions {
errorsRef: CurrentRef<OpenUIError[]>;
errorRevision: number;
publish?: boolean;
+ /** `createLibrary()` instance id, echoed on stream events for Debug matching. */
+ __libraryId?: string;
}
export interface StreamingObservabilityState {
@@ -133,6 +135,7 @@ export function useStreamingObservability({
errorsRef,
errorRevision,
publish = true,
+ __libraryId,
}: UseStreamingObservabilityOptions): void {
const streamRef = useRef<StreamingObservabilityState>(createStreamingObservabilityState());
@@ -146,6 +149,7 @@ export function useStreamingObservability({
response,
settledErrorKey,
);
+ const libraryIdFields = __libraryId !== undefined ? { __libraryId } : {};
if (isStreaming) {
if (update) {
@@ -158,6 +162,7 @@ export function useStreamingObservability({
responseLength: response?.length ?? 0,
parser: parserMetadata(result),
...captureStreamTiming(streamRef.current),
+ ...libraryIdFields,
message: "OpenUI Lang is streaming",
});
}
@@ -176,11 +181,12 @@ export function useStreamingObservability({
errors,
errorCount: errors.length,
...captureStreamTiming(streamRef.current),
+ ...libraryIdFields,
message:
errors.length > 0
? `OpenUI Lang settled with ${errors.length} error${errors.length === 1 ? "" : "s"}`
: "OpenUI Lang settled",
} satisfies SettledStreamEventDetail);
}
- }, [publish, isStreaming, response, result, errorsRef, errorRevision]);
+ }, [publish, isStreaming, response, result, errorsRef, errorRevision, __libraryId]);
}
diff --git a/packages/react-lang/src/library.test.ts b/packages/react-lang/src/library.test.ts
index 24f348c44..2a4226c57 100644
--- a/packages/react-lang/src/library.test.ts
+++ b/packages/react-lang/src/library.test.ts
@@ -44,6 +44,7 @@ describe("createLibrary publish", () => {
detail: Record<string, unknown>;
};
expect(event.detail["kind"]).toBe(LIBRARY_EVENT_KIND);
+ expect(event.detail["__libraryId"]).toBe(library.__libraryId);
expect(event.detail["id"]).toBe("demo");
expect(event.detail["root"]).toBe("Card");
expect(event.detail["components"]).toEqual(["Card"]);
diff --git a/packages/react-lang/src/publishLibrary.ts b/packages/react-lang/src/publishLibrary.ts
index 193246e36..229fd58d7 100644
--- a/packages/react-lang/src/publishLibrary.ts
+++ b/packages/react-lang/src/publishLibrary.ts
@@ -38,6 +38,7 @@ export function publishLibrary(library: Library): void {
upsertRegistry(library);
observability.info({
kind: LIBRARY_EVENT_KIND,
+ __libraryId: library.__libraryId,
...(library.id !== undefined ? { id: library.id } : {}),
...(library.root !== undefined ? { root: library.root } : {}),
components: Object.keys(library.components),