@embedpdf/plugin-metadata 3.0.0-next.14 → 3.0.0-next.15

package/dist/contract-BQQulRec.cjs

@@ -0,0 +1,22 @@
+//#region src/token.ts
+/** The package token — created once here; `contract.ts` re-exports it and
+*  `host-contract.ts` widens it. */
+const MetadataToken = (0, require("@embedpdf/core").createCapabilityToken)("metadata", {
+	hint: "add metadataPlugin() from '@embedpdf/plugin-metadata' to your plugins list",
+	promises: {
+		update: true,
+		refresh: true,
+		ensureLoaded: true,
+		"custom.update": true,
+		"custom.refresh": true
+	}
+});
+//#endregion
+Object.defineProperty(exports, "MetadataToken", {
+	enumerable: true,
+	get: function() {
+		return MetadataToken;
+	}
+});
+
+//# sourceMappingURL=contract-BQQulRec.cjs.map

package/dist/contract-BQQulRec.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-BQQulRec.cjs","names":[],"sources":["../src/token.ts"],"sourcesContent":["/** The package token — created once here; `contract.ts` re-exports it and\n *  `host-contract.ts` widens it. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { MetadataCapability } from './contract';\n\nexport const MetadataToken = createCapabilityToken<MetadataCapability>('metadata', {\n  hint: \"add metadataPlugin() from '@embedpdf/plugin-metadata' to your plugins list\",\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    update: true,\n    refresh: true,\n    ensureLoaded: true,\n    'custom.update': true,\n    'custom.refresh': true,\n  },\n});\n"],"mappings":";;;AAMA,MAAa,iBAAA,2BAAA,CAAA,CAAA,sBAAA,CAA0D,YAAY;CACjF,MAAM;CAGN,UAAU;EACR,QAAQ;EACR,SAAS;EACT,cAAc;EACd,iBAAiB;EACjB,kBAAkB;CACpB;AACF,CAAC"}

package/dist/contract-Cljrf00d.d.cts

@@ -0,0 +1,101 @@
+import { CustomMetadata, CustomMetadataPatch, DocumentMetadata, EventHook, EventOrigin, MetadataPatch, OperationOptions, ResourceStatus } from "@embedpdf/core";
+//#region src/token.d.ts
+declare const MetadataToken: import("@embedpdf/core").CapabilityToken<MetadataCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * A confirmed change of the Info dict's standard fields. Local edits, other
+ * plugins, scripts and other sessions all reach the same confirmed
+ * `metadata.updated` document event, which is the one path that updates the
+ * snapshot and fires this.
+ */
+interface MetadataUpdatedEvent {
+  readonly metadata: DocumentMetadata;
+  readonly previous: DocumentMetadata | null;
+  readonly changedKeys: readonly (keyof DocumentMetadata)[];
+  readonly origin: EventOrigin;
+}
+/** The metadata was (re)loaded from the engine. */
+interface MetadataResyncedEvent {
+  readonly metadata: DocumentMetadata;
+}
+/** A confirmed change of the custom keys (`metadata.customUpdated`), whoever caused it. */
+interface CustomMetadataUpdatedEvent {
+  readonly custom: CustomMetadata;
+  readonly previous: CustomMetadata | null;
+  /** The keys that were added, changed or removed. */
+  readonly changedKeys: readonly string[];
+  readonly origin: EventOrigin;
+}
+/** The custom keys were (re)loaded from the engine. */
+interface CustomMetadataResyncedEvent {
+  readonly custom: CustomMetadata;
+}
+/**
+ * The Info dict's custom keys: the same reads and verbs as the standard
+ * fields, on an object of their own. Changing them needs the same permission,
+ * so `canUpdate()` on the metadata capability answers for both.
+ */
+interface CustomMetadataCapability {
+  /** The current keys, reference-stable until they change; `null` until the first read lands. */
+  getSnapshot(): CustomMetadata | null;
+  /** Load state: `idle` until `ensureLoaded()` asks, then `loading` → `ready`, or `forbidden` / `error`. */
+  getStatus(): ResourceStatus;
+  /**
+   * Set and remove keys: a key left out stays, `null` removes it, a string
+   * sets it. Resolves `{ custom }`, the keys after the change; by then the
+   * snapshot shows it and `onUpdated` has fired. Rejects with
+   * `permission-denied`, `invalid-input`, `instance-closed` or
+   * `operation-cancelled`.
+   */
+  update(patch: CustomMetadataPatch, options?: OperationOptions): Promise<{
+    readonly custom: CustomMetadata;
+  }>;
+  /** Re-read from the engine. Rarely needed: the event stream keeps the snapshot fresh. */
+  refresh(options?: OperationOptions): Promise<void>;
+  /** A confirmed change, whoever caused it. Fires after the snapshot changed. */
+  readonly onUpdated: EventHook<CustomMetadataUpdatedEvent>;
+  /** The keys were loaded or reloaded from the engine. */
+  readonly onResynced: EventHook<CustomMetadataResyncedEvent>;
+}
+interface MetadataCapability {
+  /**
+   * The current metadata, reference-stable until it changes; `null` until
+   * the first read lands or while reading is forbidden — see `getStatus()`.
+   */
+  getSnapshot(): DocumentMetadata | null;
+  /** Load state: `idle` until `ensureLoaded()` asks, then `loading` → `ready`, or `forbidden` / `error`. */
+  getStatus(): ResourceStatus;
+  /**
+   * Read the standard fields and the custom keys from the document, unless they are loaded or
+   * loading: nothing reads them when a document opens. Resolves once both have landed, when
+   * `onResynced` has fired; a later call resolves at once. Rejects with `permission-denied` when
+   * reading is refused, `operation-cancelled` or `instance-closed`; after a failure it reads again.
+   */
+  ensureLoaded(options?: OperationOptions): Promise<void>;
+  /**
+   * Whether this session may change the Info dict (`doc.metadata.modify`):
+   * `update()` and `custom.update()`. The engine enforces the same permission.
+   */
+  canUpdate(): boolean;
+  /**
+   * Change the standard fields: a field left out stays, `null` clears it, a
+   * value sets it. Resolves `{ metadata }`, the fields after the change; by
+   * then the snapshot shows it and `onUpdated` has fired. Rejects with
+   * `permission-denied`, `instance-closed` or `operation-cancelled`.
+   */
+  update(patch: MetadataPatch, options?: OperationOptions): Promise<{
+    readonly metadata: DocumentMetadata;
+  }>;
+  /** Re-read from the engine. Rarely needed: the event stream keeps the snapshot fresh. */
+  refresh(options?: OperationOptions): Promise<void>;
+  /** A confirmed change, whoever caused it. Fires after the snapshot changed. */
+  readonly onUpdated: EventHook<MetadataUpdatedEvent>;
+  /** The metadata was loaded or reloaded from the engine. */
+  readonly onResynced: EventHook<MetadataResyncedEvent>;
+  /** The Info dict's other keys. */
+  readonly custom: CustomMetadataCapability;
+}
+//#endregion
+export { MetadataResyncedEvent as a, MetadataCapability as i, CustomMetadataResyncedEvent as n, MetadataUpdatedEvent as o, CustomMetadataUpdatedEvent as r, MetadataToken as s, CustomMetadataCapability as t };
+//# sourceMappingURL=contract-Cljrf00d.d.cts.map

package/dist/contract-Cljrf00d.d.ts

@@ -0,0 +1,101 @@
+import { CustomMetadata, CustomMetadataPatch, DocumentMetadata, EventHook, EventOrigin, MetadataPatch, OperationOptions, ResourceStatus } from "@embedpdf/core";
+//#region src/token.d.ts
+declare const MetadataToken: import("@embedpdf/core").CapabilityToken<MetadataCapability>;
+//#endregion
+//#region src/contract.d.ts
+/**
+ * A confirmed change of the Info dict's standard fields. Local edits, other
+ * plugins, scripts and other sessions all reach the same confirmed
+ * `metadata.updated` document event, which is the one path that updates the
+ * snapshot and fires this.
+ */
+interface MetadataUpdatedEvent {
+  readonly metadata: DocumentMetadata;
+  readonly previous: DocumentMetadata | null;
+  readonly changedKeys: readonly (keyof DocumentMetadata)[];
+  readonly origin: EventOrigin;
+}
+/** The metadata was (re)loaded from the engine. */
+interface MetadataResyncedEvent {
+  readonly metadata: DocumentMetadata;
+}
+/** A confirmed change of the custom keys (`metadata.customUpdated`), whoever caused it. */
+interface CustomMetadataUpdatedEvent {
+  readonly custom: CustomMetadata;
+  readonly previous: CustomMetadata | null;
+  /** The keys that were added, changed or removed. */
+  readonly changedKeys: readonly string[];
+  readonly origin: EventOrigin;
+}
+/** The custom keys were (re)loaded from the engine. */
+interface CustomMetadataResyncedEvent {
+  readonly custom: CustomMetadata;
+}
+/**
+ * The Info dict's custom keys: the same reads and verbs as the standard
+ * fields, on an object of their own. Changing them needs the same permission,
+ * so `canUpdate()` on the metadata capability answers for both.
+ */
+interface CustomMetadataCapability {
+  /** The current keys, reference-stable until they change; `null` until the first read lands. */
+  getSnapshot(): CustomMetadata | null;
+  /** Load state: `idle` until `ensureLoaded()` asks, then `loading` → `ready`, or `forbidden` / `error`. */
+  getStatus(): ResourceStatus;
+  /**
+   * Set and remove keys: a key left out stays, `null` removes it, a string
+   * sets it. Resolves `{ custom }`, the keys after the change; by then the
+   * snapshot shows it and `onUpdated` has fired. Rejects with
+   * `permission-denied`, `invalid-input`, `instance-closed` or
+   * `operation-cancelled`.
+   */
+  update(patch: CustomMetadataPatch, options?: OperationOptions): Promise<{
+    readonly custom: CustomMetadata;
+  }>;
+  /** Re-read from the engine. Rarely needed: the event stream keeps the snapshot fresh. */
+  refresh(options?: OperationOptions): Promise<void>;
+  /** A confirmed change, whoever caused it. Fires after the snapshot changed. */
+  readonly onUpdated: EventHook<CustomMetadataUpdatedEvent>;
+  /** The keys were loaded or reloaded from the engine. */
+  readonly onResynced: EventHook<CustomMetadataResyncedEvent>;
+}
+interface MetadataCapability {
+  /**
+   * The current metadata, reference-stable until it changes; `null` until
+   * the first read lands or while reading is forbidden — see `getStatus()`.
+   */
+  getSnapshot(): DocumentMetadata | null;
+  /** Load state: `idle` until `ensureLoaded()` asks, then `loading` → `ready`, or `forbidden` / `error`. */
+  getStatus(): ResourceStatus;
+  /**
+   * Read the standard fields and the custom keys from the document, unless they are loaded or
+   * loading: nothing reads them when a document opens. Resolves once both have landed, when
+   * `onResynced` has fired; a later call resolves at once. Rejects with `permission-denied` when
+   * reading is refused, `operation-cancelled` or `instance-closed`; after a failure it reads again.
+   */
+  ensureLoaded(options?: OperationOptions): Promise<void>;
+  /**
+   * Whether this session may change the Info dict (`doc.metadata.modify`):
+   * `update()` and `custom.update()`. The engine enforces the same permission.
+   */
+  canUpdate(): boolean;
+  /**
+   * Change the standard fields: a field left out stays, `null` clears it, a
+   * value sets it. Resolves `{ metadata }`, the fields after the change; by
+   * then the snapshot shows it and `onUpdated` has fired. Rejects with
+   * `permission-denied`, `instance-closed` or `operation-cancelled`.
+   */
+  update(patch: MetadataPatch, options?: OperationOptions): Promise<{
+    readonly metadata: DocumentMetadata;
+  }>;
+  /** Re-read from the engine. Rarely needed: the event stream keeps the snapshot fresh. */
+  refresh(options?: OperationOptions): Promise<void>;
+  /** A confirmed change, whoever caused it. Fires after the snapshot changed. */
+  readonly onUpdated: EventHook<MetadataUpdatedEvent>;
+  /** The metadata was loaded or reloaded from the engine. */
+  readonly onResynced: EventHook<MetadataResyncedEvent>;
+  /** The Info dict's other keys. */
+  readonly custom: CustomMetadataCapability;
+}
+//#endregion
+export { MetadataResyncedEvent as a, MetadataCapability as i, CustomMetadataResyncedEvent as n, MetadataUpdatedEvent as o, CustomMetadataUpdatedEvent as r, MetadataToken as s, CustomMetadataCapability as t };
+//# sourceMappingURL=contract-Cljrf00d.d.ts.map

package/dist/contract-o3j9MoH5.js

@@ -0,0 +1,18 @@
+import { createCapabilityToken } from "@embedpdf/core";
+//#region src/token.ts
+/** The package token — created once here; `contract.ts` re-exports it and
+*  `host-contract.ts` widens it. */
+const MetadataToken = createCapabilityToken("metadata", {
+	hint: "add metadataPlugin() from '@embedpdf/plugin-metadata' to your plugins list",
+	promises: {
+		update: true,
+		refresh: true,
+		ensureLoaded: true,
+		"custom.update": true,
+		"custom.refresh": true
+	}
+});
+//#endregion
+export { MetadataToken as t };
+
+//# sourceMappingURL=contract-o3j9MoH5.js.map

package/dist/contract-o3j9MoH5.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-o3j9MoH5.js","names":[],"sources":["../src/token.ts"],"sourcesContent":["/** The package token — created once here; `contract.ts` re-exports it and\n *  `host-contract.ts` widens it. */\nimport { createCapabilityToken } from '@embedpdf/core';\n\nimport type { MetadataCapability } from './contract';\n\nexport const MetadataToken = createCapabilityToken<MetadataCapability>('metadata', {\n  hint: \"add metadataPlugin() from '@embedpdf/plugin-metadata' to your plugins list\",\n  // Without a document, an adapter's stand-in rejects these with `not-ready`, as the\n  // capability would; the type asks for every member that returns a promise.\n  promises: {\n    update: true,\n    refresh: true,\n    ensureLoaded: true,\n    'custom.update': true,\n    'custom.refresh': true,\n  },\n});\n"],"mappings":";;;;AAMA,MAAa,gBAAgB,sBAA0C,YAAY;CACjF,MAAM;CAGN,UAAU;EACR,QAAQ;EACR,SAAS;EACT,cAAc;EACd,iBAAiB;EACjB,kBAAkB;CACpB;AACF,CAAC"}

package/dist/contract.cjs

@@ -1,3 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-CqhcLHxo.cjs");
+const require_contract = require("./contract-BQQulRec.cjs");
 exports.MetadataToken = require_contract.MetadataToken;

package/dist/contract.d.cts

@@ -1,2 +1,2 @@
-import { i as MetadataToken, n as MetadataCapability, r as MetadataState } from "./contract-Dk5SGhEP.cjs";
-export { type MetadataCapability, type MetadataState, MetadataToken };
+import { a as MetadataResyncedEvent, i as MetadataCapability, n as CustomMetadataResyncedEvent, o as MetadataUpdatedEvent, r as CustomMetadataUpdatedEvent, s as MetadataToken, t as CustomMetadataCapability } from "./contract-Cljrf00d.cjs";
+export { CustomMetadataCapability, CustomMetadataResyncedEvent, CustomMetadataUpdatedEvent, MetadataCapability, MetadataResyncedEvent, MetadataToken, MetadataUpdatedEvent };

package/dist/contract.d.ts

@@ -1,2 +1,2 @@
-import { i as MetadataToken, n as MetadataCapability, r as MetadataState } from "./contract-Dk5SGhEP.js";
-export { type MetadataCapability, type MetadataState, MetadataToken };
+import { a as MetadataResyncedEvent, i as MetadataCapability, n as CustomMetadataResyncedEvent, o as MetadataUpdatedEvent, r as CustomMetadataUpdatedEvent, s as MetadataToken, t as CustomMetadataCapability } from "./contract-Cljrf00d.js";
+export { CustomMetadataCapability, CustomMetadataResyncedEvent, CustomMetadataUpdatedEvent, MetadataCapability, MetadataResyncedEvent, MetadataToken, MetadataUpdatedEvent };

package/dist/contract.js

@@ -1,2 +1,2 @@
-import { t as MetadataToken } from "./contract-DXGV7Wpx.js";
+import { t as MetadataToken } from "./contract-o3j9MoH5.js";
 export { MetadataToken };

package/dist/index.cjs

@@ -1,102 +1,135 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_contract = require("./contract-CqhcLHxo.cjs");
+const require_contract = require("./contract-BQQulRec.cjs");
 let _embedpdf_core = require("@embedpdf/core");
-//#region src/capability.ts
+//#region src/model.ts
 /**
-* Authorization for Info-dict writes. Maps to PDF bit 4 (MODIFY). The engine
-* ALSO enforces this — `metadata.update` throws `PermissionDenied` without it,
-* identically on local and cloud — so `canEdit()` is the UI mirror of a real
-* guard, not the guard itself. Typed as `DocCapability` so a typo is a compile
-* error.
+* The keys whose values differ between two snapshots, removed keys included.
+* Both snapshots (the standard fields, the custom keys) hold only strings,
+* `null` and enums, so a shallow compare is exact.
 */
-const METADATA_MODIFY_CAPABILITY = "doc.metadata.modify";
+function changedKeys(previous, next) {
+	const keys = Object.keys(next);
+	if (!previous) return keys;
+	return [.../* @__PURE__ */ new Set([...Object.keys(previous), ...keys])].filter((key) => previous[key] !== next[key]);
+}
+//#endregion
+//#region src/controller.ts
+const METADATA_MODIFY = "doc.metadata.modify";
 /**
-* Reads/writes the document's Info dict through the engine handle and keeps the
-* plugin's state in sync. The live-update wiring (own + remote events) lives in
-* the effect; this is the read/write surface.
+* The metadata controller. Both halves of the Info dict are mirrors: each
+* changes only when a load lands or its confirmed document event arrives
+* (`metadata.updated`, `metadata.customUpdated`), whoever caused the edit,
+* and that is also the one place its `onUpdated` and `onResynced` fire.
+* Nothing needs them when a document opens, so they load on demand: the
+* first `ensureLoaded()` (what `metadataState` asks for) reads them.
 */
-function createMetadataCapability(ctx) {
-	const requireDoc = () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[metadata] no document bound");
-		return doc;
-	};
-	return {
-		canEdit() {
-			return ctx.doc?.security.allows(METADATA_MODIFY_CAPABILITY) ?? false;
-		},
-		current: () => ctx.getState().metadata,
-		update: async (patch) => {
-			const result = await requireDoc().metadata.update(patch);
-			ctx.dispatch({
-				type: "SET",
-				metadata: result.metadata
+function createMetadataController(ctx) {
+	const updated = ctx.events.source();
+	const resynced = ctx.events.source();
+	const customUpdated = ctx.events.source();
+	const customResynced = ctx.events.source();
+	const metadata = ctx.mirror({
+		name: "metadata",
+		onDemand: true,
+		initial: () => null,
+		load: async (doc) => ({ value: await doc.metadata.get() }),
+		fold: (value, event) => event.type === "metadata.updated" ? event.metadata : value,
+		changed: ({ cause, event, previous, next }) => {
+			if (!next) return;
+			if (cause === "load") resynced.emit({ metadata: next });
+			else if (event && "origin" in event) updated.emit({
+				metadata: next,
+				previous,
+				changedKeys: changedKeys(previous, next),
+				origin: event.origin
 			});
-		},
-		reload: async () => {
-			const metadata = await requireDoc().metadata.read();
-			ctx.dispatch({
-				type: "SET",
-				metadata
+		}
+	});
+	const custom = ctx.mirror({
+		name: "customMetadata",
+		onDemand: true,
+		initial: () => null,
+		load: async (doc) => ({ value: await doc.metadata.custom.get() }),
+		fold: (value, event) => event.type === "metadata.customUpdated" ? event.custom : value,
+		changed: ({ cause, event, previous, next }) => {
+			if (!next) return;
+			if (cause === "load") customResynced.emit({ custom: next });
+			else if (event && "origin" in event) customUpdated.emit({
+				custom: next,
+				previous,
+				changedKeys: changedKeys(previous, next),
+				origin: event.origin
 			});
 		}
-	};
-}
-//#endregion
-//#region src/effects.ts
-/**
-* Makes metadata REACTIVE — the reason this is a plugin, not a kernel IO call.
-*
-*  1. Seed: read the Info dict once when the document opens.
-*  2. Live: subscribe to the document event stream. A `metadata.updated` event
-*     carries the full re-read metadata and fires for OWN edits AND for remote
-*     edits delivered over SSE (another session) — both just become `setState`.
-*
-* The handle's stream is synchronous fan-out, so this coexists with the kernel's
-* own subscription (page registry) on the same handle.
-*/
-function registerMetadataEffects(ctx) {
-	const doc = ctx.doc;
-	if (!doc) return;
-	doc.metadata.read().then((metadata) => ctx.dispatch({
-		type: "SET",
-		metadata
-	}), () => {});
-	const unsubscribe = doc.events.subscribe((event) => {
-		if (event.type === "metadata.updated") ctx.dispatch({
-			type: "SET",
-			metadata: event.metadata
-		});
 	});
-	ctx.cleanup(unsubscribe);
+	const canUpdate = () => ctx.allows(METADATA_MODIFY);
+	/**
+	* Both writes refuse the same way before reaching the engine: the verbs are
+	* async, so a refusal rejects, and nothing changes.
+	*/
+	const refuseWrite = (verb, options) => {
+		ctx.assertAllowed(METADATA_MODIFY, verb);
+		if (options?.signal?.aborted) throw new _embedpdf_core.PluginError("operation-cancelled", "metadata", `${verb} was cancelled`);
+	};
+	const customApi = {
+		getSnapshot: custom.get,
+		getStatus: custom.getStatus,
+		update: async (patch, options) => {
+			refuseWrite("metadata.custom.update", options);
+			return { custom: (await ctx.cancellable(options?.signal, ctx.doc.metadata.custom.update(patch))).custom };
+		},
+		refresh: (options) => ctx.cancellable(options?.signal, custom.refresh()),
+		onUpdated: customUpdated.on,
+		onResynced: customResynced.on
+	};
+	return { api: {
+		getSnapshot: metadata.get,
+		getStatus: metadata.getStatus,
+		ensureLoaded: (options) => ctx.cancellable(options?.signal, Promise.all([metadata.ensureLoaded(), custom.ensureLoaded()]).then(() => void 0)),
+		canUpdate,
+		update: async (patch, options) => {
+			refuseWrite("metadata.update", options);
+			return { metadata: (await ctx.cancellable(options?.signal, ctx.doc.metadata.update(patch))).metadata };
+		},
+		refresh: (options) => ctx.cancellable(options?.signal, metadata.refresh()),
+		onUpdated: updated.on,
+		onResynced: resynced.on,
+		custom: customApi
+	} };
 }
 //#endregion
-//#region src/reducer.ts
-const initialMetadataState = () => ({ metadata: null });
-/** Pure. The only transition: replace the metadata snapshot (from a read or an
-*  event). */
-const metadataReducer = (state, a) => a.type === "SET" ? {
-	...state,
-	metadata: a.metadata
-} : state;
-//#endregion
 //#region src/metadata.plugin.ts
-/**
-* Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it
-* from the engine and keeps it live off the document event stream (own + remote
-* SSE edits); the capability is the read/write surface.
-*/
+/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */
 const metadataPlugin = () => (0, _embedpdf_core.definePlugin)({
 	id: "metadata",
 	token: require_contract.MetadataToken,
 	scope: "document",
-	initialState: initialMetadataState,
-	reduce: metadataReducer,
-	capability: createMetadataCapability,
-	effects: registerMetadataEffects
+	create: createMetadataController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The metadata page's State table as code: what `useMetadataState()` returns,
+* and the same fields in every other framework. `status` is the standard
+* fields' load state; `custom.getStatus()` has the custom keys' own. Reading
+* the state loads it (`ensure`): the first reader of a document starts the read.
+*/
+const metadataState = (0, _embedpdf_core.defineState)(require_contract.MetadataToken, {
+	read: (metadata) => ({
+		metadata: metadata.getSnapshot(),
+		custom: metadata.custom.getSnapshot(),
+		status: metadata.getStatus()
+	}),
+	empty: {
+		metadata: null,
+		custom: null,
+		status: "idle"
+	},
+	ensure: (metadata) => metadata.ensureLoaded()
 });
 //#endregion
 exports.MetadataToken = require_contract.MetadataToken;
 exports.metadataPlugin = metadataPlugin;
+exports.metadataState = metadataState;
 
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["MetadataToken"],"sources":["../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/metadata.plugin.ts"],"sourcesContent":["import type { PluginContext, DocCapability } from '@embedpdf/core';\nimport type { MetadataAction, MetadataCapability, MetadataState } from './types';\n\n/**\n * Authorization for Info-dict writes. Maps to PDF bit 4 (MODIFY). The engine\n * ALSO enforces this — `metadata.update` throws `PermissionDenied` without it,\n * identically on local and cloud — so `canEdit()` is the UI mirror of a real\n * guard, not the guard itself. Typed as `DocCapability` so a typo is a compile\n * error.\n */\nconst METADATA_MODIFY_CAPABILITY: DocCapability = 'doc.metadata.modify';\n\n/**\n * Reads/writes the document's Info dict through the engine handle and keeps the\n * plugin's state in sync. The live-update wiring (own + remote events) lives in\n * the effect; this is the read/write surface.\n */\nexport function createMetadataCapability(\n  ctx: PluginContext<MetadataState, MetadataAction>,\n): MetadataCapability {\n  const requireDoc = () => {\n    const doc = ctx.doc;\n    if (!doc) throw new Error('[metadata] no document bound');\n    return doc;\n  };\n\n  return {\n    canEdit() {\n      // Wildcard-aware predicate (mirrors the engine's own enforcement),\n      // identical on both engines. NOT `effectiveScope.includes(...)` — that\n      // enumeration drops the `*` admin grant, so it would hide the UI on a\n      // default admin open even though the engine allows the edit.\n      return ctx.doc?.security.allows(METADATA_MODIFY_CAPABILITY) ?? false;\n    },\n\n    current: () => ctx.getState().metadata,\n\n    update: async (patch) => {\n      // The write also emits a `metadata.updated` event the effect catches, so\n      // this dispatch is just for an immediate, in-sync update (idempotent).\n      const result = await requireDoc().metadata.update(patch);\n      ctx.dispatch({ type: 'SET', metadata: result.metadata });\n    },\n\n    reload: async () => {\n      const metadata = await requireDoc().metadata.read();\n      ctx.dispatch({ type: 'SET', metadata });\n    },\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport type { MetadataAction, MetadataState } from './types';\n\n/**\n * Makes metadata REACTIVE — the reason this is a plugin, not a kernel IO call.\n *\n *  1. Seed: read the Info dict once when the document opens.\n *  2. Live: subscribe to the document event stream. A `metadata.updated` event\n *     carries the full re-read metadata and fires for OWN edits AND for remote\n *     edits delivered over SSE (another session) — both just become `setState`.\n *\n * The handle's stream is synchronous fan-out, so this coexists with the kernel's\n * own subscription (page registry) on the same handle.\n */\nexport function registerMetadataEffects(ctx: EffectContext<MetadataState, MetadataAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  // 1. seed\n  void doc.metadata.read().then(\n    (metadata) => ctx.dispatch({ type: 'SET', metadata }),\n    () => {}, // doc closed / read aborted — ignore\n  );\n\n  // 2. live updates (own edits + remote SSE edits)\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    if (event.type === 'metadata.updated') {\n      ctx.dispatch({ type: 'SET', metadata: event.metadata });\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { MetadataAction, MetadataState } from './types';\n\nexport const initialMetadataState = (): MetadataState => ({ metadata: null });\n\n/** Pure. The only transition: replace the metadata snapshot (from a read or an\n *  event). */\nexport const metadataReducer = (state: MetadataState, a: MetadataAction): MetadataState =>\n  a.type === 'SET' ? { ...state, metadata: a.metadata } : state;\n","import { definePlugin } from '@embedpdf/core';\nimport { createMetadataCapability } from './capability';\nimport { registerMetadataEffects } from './effects';\nimport { initialMetadataState, metadataReducer } from './reducer';\nimport { MetadataToken } from './types';\nimport type { MetadataAction, MetadataCapability, MetadataState } from './types';\n\n/**\n * Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it\n * from the engine and keeps it live off the document event stream (own + remote\n * SSE edits); the capability is the read/write surface.\n */\nexport const metadataPlugin = () =>\n  definePlugin<MetadataState, MetadataAction, MetadataCapability>({\n    id: 'metadata',\n    token: MetadataToken,\n    scope: 'document',\n    initialState: initialMetadataState,\n    reduce: metadataReducer,\n    capability: createMetadataCapability,\n    effects: registerMetadataEffects,\n  });\n"],"mappings":";;;;;;;;;;;AAUA,MAAM,6BAA4C;;;;;;AAOlD,SAAgB,yBACd,KACoB;CACpB,MAAM,mBAAmB;EACvB,MAAM,MAAM,IAAI;EAChB,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,8BAA8B;EACxD,OAAO;CACT;CAEA,OAAO;EACL,UAAU;GAKR,OAAO,IAAI,KAAK,SAAS,OAAO,0BAA0B,KAAK;EACjE;EAEA,eAAe,IAAI,SAAS,CAAC,CAAC;EAE9B,QAAQ,OAAO,UAAU;GAGvB,MAAM,SAAS,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,KAAK;GACvD,IAAI,SAAS;IAAE,MAAM;IAAO,UAAU,OAAO;GAAS,CAAC;EACzD;EAEA,QAAQ,YAAY;GAClB,MAAM,WAAW,MAAM,WAAW,CAAC,CAAC,SAAS,KAAK;GAClD,IAAI,SAAS;IAAE,MAAM;IAAO;GAAS,CAAC;EACxC;CACF;AACF;;;;;;;;;;;;;;ACnCA,SAAgB,wBAAwB,KAAyD;CAC/F,MAAM,MAAM,IAAI;CAChB,IAAI,CAAC,KAAK;CAGV,IAAS,SAAS,KAAK,CAAC,CAAC,MACtB,aAAa,IAAI,SAAS;EAAE,MAAM;EAAO;CAAS,CAAC,SAC9C,CAAC,CACT;CAGA,MAAM,cAAc,IAAI,OAAO,WAAW,UAAyB;EACjE,IAAI,MAAM,SAAS,oBACjB,IAAI,SAAS;GAAE,MAAM;GAAO,UAAU,MAAM;EAAS,CAAC;CAE1D,CAAC;CACD,IAAI,QAAQ,WAAW;AACzB;;;AC7BA,MAAa,8BAA6C,EAAE,UAAU,KAAK;;;AAI3E,MAAa,mBAAmB,OAAsB,MACpD,EAAE,SAAS,QAAQ;CAAE,GAAG;CAAO,UAAU,EAAE;AAAS,IAAI;;;;;;;;ACK1D,MAAa,wBAAA,GAAA,eAAA,aAAA,CACqD;CAC9D,IAAI;CACJ,OAAOA,iBAAAA;CACP,OAAO;CACP,cAAc;CACd,QAAQ;CACR,YAAY;CACZ,SAAS;AACX,CAAC"}
+{"version":3,"file":"index.cjs","names":["PluginError","MetadataToken","MetadataToken"],"sources":["../src/model.ts","../src/controller.ts","../src/metadata.plugin.ts","../src/state.ts"],"sourcesContent":["/**\n * The keys whose values differ between two snapshots, removed keys included.\n * Both snapshots (the standard fields, the custom keys) hold only strings,\n * `null` and enums, so a shallow compare is exact.\n */\nexport function changedKeys<T extends object>(\n  previous: T | null,\n  next: T,\n): readonly (keyof T & string)[] {\n  const keys = Object.keys(next) as (keyof T & string)[];\n  if (!previous) return keys;\n  const all = new Set([...(Object.keys(previous) as (keyof T & string)[]), ...keys]);\n  return [...all].filter((key) => previous[key] !== next[key]);\n}\n","import {\n  PluginError,\n  type PluginContext,\n  type CustomMetadata,\n  type DocCapability,\n  type DocumentMetadata,\n  type OperationOptions,\n} from '@embedpdf/core';\n\nimport type {\n  CustomMetadataCapability,\n  CustomMetadataResyncedEvent,\n  CustomMetadataUpdatedEvent,\n  MetadataCapability,\n  MetadataResyncedEvent,\n  MetadataUpdatedEvent,\n} from './contract';\nimport { changedKeys } from './model';\n\nconst METADATA_MODIFY: DocCapability = 'doc.metadata.modify';\n\n/**\n * The metadata controller. Both halves of the Info dict are mirrors: each\n * changes only when a load lands or its confirmed document event arrives\n * (`metadata.updated`, `metadata.customUpdated`), whoever caused the edit,\n * and that is also the one place its `onUpdated` and `onResynced` fire.\n * Nothing needs them when a document opens, so they load on demand: the\n * first `ensureLoaded()` (what `metadataState` asks for) reads them.\n */\nexport function createMetadataController(ctx: PluginContext<void>) {\n  const updated = ctx.events.source<MetadataUpdatedEvent>();\n  const resynced = ctx.events.source<MetadataResyncedEvent>();\n  const customUpdated = ctx.events.source<CustomMetadataUpdatedEvent>();\n  const customResynced = ctx.events.source<CustomMetadataResyncedEvent>();\n\n  const metadata = ctx.mirror<DocumentMetadata | null>({\n    name: 'metadata',\n    onDemand: true,\n    initial: () => null,\n    load: async (doc) => ({ value: await doc.metadata.get() }),\n    fold: (value, event) => (event.type === 'metadata.updated' ? event.metadata : value),\n    changed: ({ cause, event, previous, next }) => {\n      if (!next) return;\n      if (cause === 'load') {\n        resynced.emit({ metadata: next });\n      } else if (event && 'origin' in event) {\n        updated.emit({\n          metadata: next,\n          previous,\n          changedKeys: changedKeys(previous, next),\n          origin: event.origin,\n        });\n      }\n    },\n  });\n\n  const custom = ctx.mirror<CustomMetadata | null>({\n    name: 'customMetadata',\n    onDemand: true,\n    initial: () => null,\n    load: async (doc) => ({ value: await doc.metadata.custom.get() }),\n    fold: (value, event) => (event.type === 'metadata.customUpdated' ? event.custom : value),\n    changed: ({ cause, event, previous, next }) => {\n      if (!next) return;\n      if (cause === 'load') {\n        customResynced.emit({ custom: next });\n      } else if (event && 'origin' in event) {\n        customUpdated.emit({\n          custom: next,\n          previous,\n          changedKeys: changedKeys(previous, next),\n          origin: event.origin,\n        });\n      }\n    },\n  });\n\n  const canUpdate = () => ctx.allows(METADATA_MODIFY);\n\n  /**\n   * Both writes refuse the same way before reaching the engine: the verbs are\n   * async, so a refusal rejects, and nothing changes.\n   */\n  const refuseWrite = (verb: string, options?: OperationOptions): void => {\n    ctx.assertAllowed(METADATA_MODIFY, verb);\n    if (options?.signal?.aborted) {\n      throw new PluginError('operation-cancelled', 'metadata', `${verb} was cancelled`);\n    }\n  };\n\n  const customApi: CustomMetadataCapability = {\n    getSnapshot: custom.get,\n    getStatus: custom.getStatus,\n    update: async (patch, options) => {\n      refuseWrite('metadata.custom.update', options);\n      const result = await ctx.cancellable(options?.signal, ctx.doc.metadata.custom.update(patch));\n      return { custom: result.custom };\n    },\n    refresh: (options) => ctx.cancellable(options?.signal, custom.refresh()),\n    onUpdated: customUpdated.on,\n    onResynced: customResynced.on,\n  };\n\n  const api: MetadataCapability = {\n    getSnapshot: metadata.get,\n    getStatus: metadata.getStatus,\n    ensureLoaded: (options) =>\n      ctx.cancellable(\n        options?.signal,\n        Promise.all([metadata.ensureLoaded(), custom.ensureLoaded()]).then(() => undefined),\n      ),\n    canUpdate,\n    update: async (patch, options) => {\n      refuseWrite('metadata.update', options);\n      const result = await ctx.cancellable(options?.signal, ctx.doc.metadata.update(patch));\n      return { metadata: result.metadata };\n    },\n    refresh: (options) => ctx.cancellable(options?.signal, metadata.refresh()),\n    onUpdated: updated.on,\n    onResynced: resynced.on,\n    custom: customApi,\n  };\n\n  return { api };\n}\n","import { definePlugin } from '@embedpdf/core';\n\nimport { MetadataToken } from './contract';\nimport { createMetadataController } from './controller';\n\n/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */\nexport const metadataPlugin = () =>\n  definePlugin({\n    id: 'metadata',\n    token: MetadataToken,\n    scope: 'document',\n    create: createMetadataController,\n  });\n","/**\n * The metadata page's State table as code: what `useMetadataState()` returns,\n * and the same fields in every other framework. `status` is the standard\n * fields' load state; `custom.getStatus()` has the custom keys' own. Reading\n * the state loads it (`ensure`): the first reader of a document starts the read.\n */\nimport { defineState } from '@embedpdf/core';\n\nimport { MetadataToken } from './contract';\n\nexport const metadataState = defineState(MetadataToken, {\n  read: (metadata) => ({\n    metadata: metadata.getSnapshot(),\n    custom: metadata.custom.getSnapshot(),\n    status: metadata.getStatus(),\n  }),\n  empty: {\n    metadata: null,\n    custom: null,\n    status: 'idle',\n  },\n  ensure: (metadata) => metadata.ensureLoaded(),\n});\n"],"mappings":";;;;;;;;;AAKA,SAAgB,YACd,UACA,MAC+B;CAC/B,MAAM,OAAO,OAAO,KAAK,IAAI;CAC7B,IAAI,CAAC,UAAU,OAAO;CAEtB,OAAO,CAAC,mBAAG,IADK,IAAI,CAAC,GAAI,OAAO,KAAK,QAAQ,GAA4B,GAAG,IAAI,CACnE,CAAC,CAAC,CAAC,QAAQ,QAAQ,SAAS,SAAS,KAAK,IAAI;AAC7D;;;ACMA,MAAM,kBAAiC;;;;;;;;;AAUvC,SAAgB,yBAAyB,KAA0B;CACjE,MAAM,UAAU,IAAI,OAAO,OAA6B;CACxD,MAAM,WAAW,IAAI,OAAO,OAA8B;CAC1D,MAAM,gBAAgB,IAAI,OAAO,OAAmC;CACpE,MAAM,iBAAiB,IAAI,OAAO,OAAoC;CAEtE,MAAM,WAAW,IAAI,OAAgC;EACnD,MAAM;EACN,UAAU;EACV,eAAe;EACf,MAAM,OAAO,SAAS,EAAE,OAAO,MAAM,IAAI,SAAS,IAAI,EAAE;EACxD,OAAO,OAAO,UAAW,MAAM,SAAS,qBAAqB,MAAM,WAAW;EAC9E,UAAU,EAAE,OAAO,OAAO,UAAU,WAAW;GAC7C,IAAI,CAAC,MAAM;GACX,IAAI,UAAU,QACZ,SAAS,KAAK,EAAE,UAAU,KAAK,CAAC;QAC3B,IAAI,SAAS,YAAY,OAC9B,QAAQ,KAAK;IACX,UAAU;IACV;IACA,aAAa,YAAY,UAAU,IAAI;IACvC,QAAQ,MAAM;GAChB,CAAC;EAEL;CACF,CAAC;CAED,MAAM,SAAS,IAAI,OAA8B;EAC/C,MAAM;EACN,UAAU;EACV,eAAe;EACf,MAAM,OAAO,SAAS,EAAE,OAAO,MAAM,IAAI,SAAS,OAAO,IAAI,EAAE;EAC/D,OAAO,OAAO,UAAW,MAAM,SAAS,2BAA2B,MAAM,SAAS;EAClF,UAAU,EAAE,OAAO,OAAO,UAAU,WAAW;GAC7C,IAAI,CAAC,MAAM;GACX,IAAI,UAAU,QACZ,eAAe,KAAK,EAAE,QAAQ,KAAK,CAAC;QAC/B,IAAI,SAAS,YAAY,OAC9B,cAAc,KAAK;IACjB,QAAQ;IACR;IACA,aAAa,YAAY,UAAU,IAAI;IACvC,QAAQ,MAAM;GAChB,CAAC;EAEL;CACF,CAAC;CAED,MAAM,kBAAkB,IAAI,OAAO,eAAe;;;;;CAMlD,MAAM,eAAe,MAAc,YAAqC;EACtE,IAAI,cAAc,iBAAiB,IAAI;EACvC,IAAI,SAAS,QAAQ,SACnB,MAAM,IAAIA,eAAAA,YAAY,uBAAuB,YAAY,GAAG,KAAK,eAAe;CAEpF;CAEA,MAAM,YAAsC;EAC1C,aAAa,OAAO;EACpB,WAAW,OAAO;EAClB,QAAQ,OAAO,OAAO,YAAY;GAChC,YAAY,0BAA0B,OAAO;GAE7C,OAAO,EAAE,SAAQ,MADI,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,SAAS,OAAO,OAAO,KAAK,CAAC,EAAA,CACnE,OAAO;EACjC;EACA,UAAU,YAAY,IAAI,YAAY,SAAS,QAAQ,OAAO,QAAQ,CAAC;EACvE,WAAW,cAAc;EACzB,YAAY,eAAe;CAC7B;CAsBA,OAAO,EAAE,KAAA;EAnBP,aAAa,SAAS;EACtB,WAAW,SAAS;EACpB,eAAe,YACb,IAAI,YACF,SAAS,QACT,QAAQ,IAAI,CAAC,SAAS,aAAa,GAAG,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,WAAW,KAAA,CAAS,CACpF;EACF;EACA,QAAQ,OAAO,OAAO,YAAY;GAChC,YAAY,mBAAmB,OAAO;GAEtC,OAAO,EAAE,WAAU,MADE,IAAI,YAAY,SAAS,QAAQ,IAAI,IAAI,SAAS,OAAO,KAAK,CAAC,EAAA,CAC1D,SAAS;EACrC;EACA,UAAU,YAAY,IAAI,YAAY,SAAS,QAAQ,SAAS,QAAQ,CAAC;EACzE,WAAW,QAAQ;EACnB,YAAY,SAAS;EACrB,QAAQ;CAGC,EAAE;AACf;;;;ACtHA,MAAa,wBAAA,GAAA,eAAA,aAAA,CACE;CACX,IAAI;CACJ,OAAOC,iBAAAA;CACP,OAAO;CACP,QAAQ;AACV,CAAC;;;;;;;;;ACFH,MAAa,iBAAA,GAAA,eAAA,YAAA,CAA4BC,iBAAAA,eAAe;CACtD,OAAO,cAAc;EACnB,UAAU,SAAS,YAAY;EAC/B,QAAQ,SAAS,OAAO,YAAY;EACpC,QAAQ,SAAS,UAAU;CAC7B;CACA,OAAO;EACL,UAAU;EACV,QAAQ;EACR,QAAQ;CACV;CACA,SAAS,aAAa,SAAS,aAAa;AAC9C,CAAC"}

package/dist/index.d.cts

@@ -1,11 +1,14 @@
-import { i as MetadataToken, n as MetadataCapability, r as MetadataState, t as MetadataAction } from "./contract-Dk5SGhEP.cjs";
+import { a as MetadataResyncedEvent, i as MetadataCapability, n as CustomMetadataResyncedEvent, o as MetadataUpdatedEvent, r as CustomMetadataUpdatedEvent, s as MetadataToken, t as CustomMetadataCapability } from "./contract-Cljrf00d.cjs";
 //#region src/metadata.plugin.d.ts
-/**
- * Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it
- * from the engine and keeps it live off the document event stream (own + remote
- * SSE edits); the capability is the read/write surface.
- */
-declare const metadataPlugin: () => import("@embedpdf/core").PluginDef<MetadataState, MetadataAction, MetadataCapability>;
+/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */
+declare const metadataPlugin: () => import("@embedpdf/core").PluginDef<void, MetadataCapability, import("@embedpdf/core").NoSettings>;
 //#endregion
-export { type MetadataCapability, type MetadataState, MetadataToken, metadataPlugin };
+//#region src/state.d.ts
+declare const metadataState: import("@embedpdf/core").StateDeclaration<MetadataCapability, {
+  metadata: import("@embedpdf/core").DocumentMetadata | null;
+  custom: import("@embedpdf/core").CustomMetadata | null;
+  status: import("@embedpdf/core").ResourceStatus;
+}>;
+//#endregion
+export { CustomMetadataCapability, CustomMetadataResyncedEvent, CustomMetadataUpdatedEvent, MetadataCapability, MetadataResyncedEvent, MetadataToken, MetadataUpdatedEvent, metadataPlugin, metadataState };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,11 +1,14 @@
-import { i as MetadataToken, n as MetadataCapability, r as MetadataState, t as MetadataAction } from "./contract-Dk5SGhEP.js";
+import { a as MetadataResyncedEvent, i as MetadataCapability, n as CustomMetadataResyncedEvent, o as MetadataUpdatedEvent, r as CustomMetadataUpdatedEvent, s as MetadataToken, t as CustomMetadataCapability } from "./contract-Cljrf00d.js";
 //#region src/metadata.plugin.d.ts
-/**
- * Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it
- * from the engine and keeps it live off the document event stream (own + remote
- * SSE edits); the capability is the read/write surface.
- */
-declare const metadataPlugin: () => import("@embedpdf/core").PluginDef<MetadataState, MetadataAction, MetadataCapability>;
+/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */
+declare const metadataPlugin: () => import("@embedpdf/core").PluginDef<void, MetadataCapability, import("@embedpdf/core").NoSettings>;
 //#endregion
-export { type MetadataCapability, type MetadataState, MetadataToken, metadataPlugin };
+//#region src/state.d.ts
+declare const metadataState: import("@embedpdf/core").StateDeclaration<MetadataCapability, {
+  metadata: import("@embedpdf/core").DocumentMetadata | null;
+  custom: import("@embedpdf/core").CustomMetadata | null;
+  status: import("@embedpdf/core").ResourceStatus;
+}>;
+//#endregion
+export { CustomMetadataCapability, CustomMetadataResyncedEvent, CustomMetadataUpdatedEvent, MetadataCapability, MetadataResyncedEvent, MetadataToken, MetadataUpdatedEvent, metadataPlugin, metadataState };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,100 +1,132 @@
-import { t as MetadataToken } from "./contract-DXGV7Wpx.js";
-import { definePlugin } from "@embedpdf/core";
-//#region src/capability.ts
+import { t as MetadataToken } from "./contract-o3j9MoH5.js";
+import { PluginError, definePlugin, defineState } from "@embedpdf/core";
+//#region src/model.ts
 /**
-* Authorization for Info-dict writes. Maps to PDF bit 4 (MODIFY). The engine
-* ALSO enforces this — `metadata.update` throws `PermissionDenied` without it,
-* identically on local and cloud — so `canEdit()` is the UI mirror of a real
-* guard, not the guard itself. Typed as `DocCapability` so a typo is a compile
-* error.
+* The keys whose values differ between two snapshots, removed keys included.
+* Both snapshots (the standard fields, the custom keys) hold only strings,
+* `null` and enums, so a shallow compare is exact.
 */
-const METADATA_MODIFY_CAPABILITY = "doc.metadata.modify";
+function changedKeys(previous, next) {
+	const keys = Object.keys(next);
+	if (!previous) return keys;
+	return [.../* @__PURE__ */ new Set([...Object.keys(previous), ...keys])].filter((key) => previous[key] !== next[key]);
+}
+//#endregion
+//#region src/controller.ts
+const METADATA_MODIFY = "doc.metadata.modify";
 /**
-* Reads/writes the document's Info dict through the engine handle and keeps the
-* plugin's state in sync. The live-update wiring (own + remote events) lives in
-* the effect; this is the read/write surface.
+* The metadata controller. Both halves of the Info dict are mirrors: each
+* changes only when a load lands or its confirmed document event arrives
+* (`metadata.updated`, `metadata.customUpdated`), whoever caused the edit,
+* and that is also the one place its `onUpdated` and `onResynced` fire.
+* Nothing needs them when a document opens, so they load on demand: the
+* first `ensureLoaded()` (what `metadataState` asks for) reads them.
 */
-function createMetadataCapability(ctx) {
-	const requireDoc = () => {
-		const doc = ctx.doc;
-		if (!doc) throw new Error("[metadata] no document bound");
-		return doc;
-	};
-	return {
-		canEdit() {
-			return ctx.doc?.security.allows(METADATA_MODIFY_CAPABILITY) ?? false;
-		},
-		current: () => ctx.getState().metadata,
-		update: async (patch) => {
-			const result = await requireDoc().metadata.update(patch);
-			ctx.dispatch({
-				type: "SET",
-				metadata: result.metadata
+function createMetadataController(ctx) {
+	const updated = ctx.events.source();
+	const resynced = ctx.events.source();
+	const customUpdated = ctx.events.source();
+	const customResynced = ctx.events.source();
+	const metadata = ctx.mirror({
+		name: "metadata",
+		onDemand: true,
+		initial: () => null,
+		load: async (doc) => ({ value: await doc.metadata.get() }),
+		fold: (value, event) => event.type === "metadata.updated" ? event.metadata : value,
+		changed: ({ cause, event, previous, next }) => {
+			if (!next) return;
+			if (cause === "load") resynced.emit({ metadata: next });
+			else if (event && "origin" in event) updated.emit({
+				metadata: next,
+				previous,
+				changedKeys: changedKeys(previous, next),
+				origin: event.origin
 			});
-		},
-		reload: async () => {
-			const metadata = await requireDoc().metadata.read();
-			ctx.dispatch({
-				type: "SET",
-				metadata
+		}
+	});
+	const custom = ctx.mirror({
+		name: "customMetadata",
+		onDemand: true,
+		initial: () => null,
+		load: async (doc) => ({ value: await doc.metadata.custom.get() }),
+		fold: (value, event) => event.type === "metadata.customUpdated" ? event.custom : value,
+		changed: ({ cause, event, previous, next }) => {
+			if (!next) return;
+			if (cause === "load") customResynced.emit({ custom: next });
+			else if (event && "origin" in event) customUpdated.emit({
+				custom: next,
+				previous,
+				changedKeys: changedKeys(previous, next),
+				origin: event.origin
 			});
 		}
-	};
-}
-//#endregion
-//#region src/effects.ts
-/**
-* Makes metadata REACTIVE — the reason this is a plugin, not a kernel IO call.
-*
-*  1. Seed: read the Info dict once when the document opens.
-*  2. Live: subscribe to the document event stream. A `metadata.updated` event
-*     carries the full re-read metadata and fires for OWN edits AND for remote
-*     edits delivered over SSE (another session) — both just become `setState`.
-*
-* The handle's stream is synchronous fan-out, so this coexists with the kernel's
-* own subscription (page registry) on the same handle.
-*/
-function registerMetadataEffects(ctx) {
-	const doc = ctx.doc;
-	if (!doc) return;
-	doc.metadata.read().then((metadata) => ctx.dispatch({
-		type: "SET",
-		metadata
-	}), () => {});
-	const unsubscribe = doc.events.subscribe((event) => {
-		if (event.type === "metadata.updated") ctx.dispatch({
-			type: "SET",
-			metadata: event.metadata
-		});
 	});
-	ctx.cleanup(unsubscribe);
+	const canUpdate = () => ctx.allows(METADATA_MODIFY);
+	/**
+	* Both writes refuse the same way before reaching the engine: the verbs are
+	* async, so a refusal rejects, and nothing changes.
+	*/
+	const refuseWrite = (verb, options) => {
+		ctx.assertAllowed(METADATA_MODIFY, verb);
+		if (options?.signal?.aborted) throw new PluginError("operation-cancelled", "metadata", `${verb} was cancelled`);
+	};
+	const customApi = {
+		getSnapshot: custom.get,
+		getStatus: custom.getStatus,
+		update: async (patch, options) => {
+			refuseWrite("metadata.custom.update", options);
+			return { custom: (await ctx.cancellable(options?.signal, ctx.doc.metadata.custom.update(patch))).custom };
+		},
+		refresh: (options) => ctx.cancellable(options?.signal, custom.refresh()),
+		onUpdated: customUpdated.on,
+		onResynced: customResynced.on
+	};
+	return { api: {
+		getSnapshot: metadata.get,
+		getStatus: metadata.getStatus,
+		ensureLoaded: (options) => ctx.cancellable(options?.signal, Promise.all([metadata.ensureLoaded(), custom.ensureLoaded()]).then(() => void 0)),
+		canUpdate,
+		update: async (patch, options) => {
+			refuseWrite("metadata.update", options);
+			return { metadata: (await ctx.cancellable(options?.signal, ctx.doc.metadata.update(patch))).metadata };
+		},
+		refresh: (options) => ctx.cancellable(options?.signal, metadata.refresh()),
+		onUpdated: updated.on,
+		onResynced: resynced.on,
+		custom: customApi
+	} };
 }
 //#endregion
-//#region src/reducer.ts
-const initialMetadataState = () => ({ metadata: null });
-/** Pure. The only transition: replace the metadata snapshot (from a read or an
-*  event). */
-const metadataReducer = (state, a) => a.type === "SET" ? {
-	...state,
-	metadata: a.metadata
-} : state;
-//#endregion
 //#region src/metadata.plugin.ts
-/**
-* Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it
-* from the engine and keeps it live off the document event stream (own + remote
-* SSE edits); the capability is the read/write surface.
-*/
+/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */
 const metadataPlugin = () => definePlugin({
 	id: "metadata",
 	token: MetadataToken,
 	scope: "document",
-	initialState: initialMetadataState,
-	reduce: metadataReducer,
-	capability: createMetadataCapability,
-	effects: registerMetadataEffects
+	create: createMetadataController
+});
+//#endregion
+//#region src/state.ts
+/**
+* The metadata page's State table as code: what `useMetadataState()` returns,
+* and the same fields in every other framework. `status` is the standard
+* fields' load state; `custom.getStatus()` has the custom keys' own. Reading
+* the state loads it (`ensure`): the first reader of a document starts the read.
+*/
+const metadataState = defineState(MetadataToken, {
+	read: (metadata) => ({
+		metadata: metadata.getSnapshot(),
+		custom: metadata.custom.getSnapshot(),
+		status: metadata.getStatus()
+	}),
+	empty: {
+		metadata: null,
+		custom: null,
+		status: "idle"
+	},
+	ensure: (metadata) => metadata.ensureLoaded()
 });
 //#endregion
-export { MetadataToken, metadataPlugin };
+export { MetadataToken, metadataPlugin, metadataState };
 
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/capability.ts","../src/effects.ts","../src/reducer.ts","../src/metadata.plugin.ts"],"sourcesContent":["import type { PluginContext, DocCapability } from '@embedpdf/core';\nimport type { MetadataAction, MetadataCapability, MetadataState } from './types';\n\n/**\n * Authorization for Info-dict writes. Maps to PDF bit 4 (MODIFY). The engine\n * ALSO enforces this — `metadata.update` throws `PermissionDenied` without it,\n * identically on local and cloud — so `canEdit()` is the UI mirror of a real\n * guard, not the guard itself. Typed as `DocCapability` so a typo is a compile\n * error.\n */\nconst METADATA_MODIFY_CAPABILITY: DocCapability = 'doc.metadata.modify';\n\n/**\n * Reads/writes the document's Info dict through the engine handle and keeps the\n * plugin's state in sync. The live-update wiring (own + remote events) lives in\n * the effect; this is the read/write surface.\n */\nexport function createMetadataCapability(\n  ctx: PluginContext<MetadataState, MetadataAction>,\n): MetadataCapability {\n  const requireDoc = () => {\n    const doc = ctx.doc;\n    if (!doc) throw new Error('[metadata] no document bound');\n    return doc;\n  };\n\n  return {\n    canEdit() {\n      // Wildcard-aware predicate (mirrors the engine's own enforcement),\n      // identical on both engines. NOT `effectiveScope.includes(...)` — that\n      // enumeration drops the `*` admin grant, so it would hide the UI on a\n      // default admin open even though the engine allows the edit.\n      return ctx.doc?.security.allows(METADATA_MODIFY_CAPABILITY) ?? false;\n    },\n\n    current: () => ctx.getState().metadata,\n\n    update: async (patch) => {\n      // The write also emits a `metadata.updated` event the effect catches, so\n      // this dispatch is just for an immediate, in-sync update (idempotent).\n      const result = await requireDoc().metadata.update(patch);\n      ctx.dispatch({ type: 'SET', metadata: result.metadata });\n    },\n\n    reload: async () => {\n      const metadata = await requireDoc().metadata.read();\n      ctx.dispatch({ type: 'SET', metadata });\n    },\n  };\n}\n","import type { DocumentEvent, EffectContext } from '@embedpdf/core';\nimport type { MetadataAction, MetadataState } from './types';\n\n/**\n * Makes metadata REACTIVE — the reason this is a plugin, not a kernel IO call.\n *\n *  1. Seed: read the Info dict once when the document opens.\n *  2. Live: subscribe to the document event stream. A `metadata.updated` event\n *     carries the full re-read metadata and fires for OWN edits AND for remote\n *     edits delivered over SSE (another session) — both just become `setState`.\n *\n * The handle's stream is synchronous fan-out, so this coexists with the kernel's\n * own subscription (page registry) on the same handle.\n */\nexport function registerMetadataEffects(ctx: EffectContext<MetadataState, MetadataAction>): void {\n  const doc = ctx.doc;\n  if (!doc) return;\n\n  // 1. seed\n  void doc.metadata.read().then(\n    (metadata) => ctx.dispatch({ type: 'SET', metadata }),\n    () => {}, // doc closed / read aborted — ignore\n  );\n\n  // 2. live updates (own edits + remote SSE edits)\n  const unsubscribe = doc.events.subscribe((event: DocumentEvent) => {\n    if (event.type === 'metadata.updated') {\n      ctx.dispatch({ type: 'SET', metadata: event.metadata });\n    }\n  });\n  ctx.cleanup(unsubscribe);\n}\n","import type { MetadataAction, MetadataState } from './types';\n\nexport const initialMetadataState = (): MetadataState => ({ metadata: null });\n\n/** Pure. The only transition: replace the metadata snapshot (from a read or an\n *  event). */\nexport const metadataReducer = (state: MetadataState, a: MetadataAction): MetadataState =>\n  a.type === 'SET' ? { ...state, metadata: a.metadata } : state;\n","import { definePlugin } from '@embedpdf/core';\nimport { createMetadataCapability } from './capability';\nimport { registerMetadataEffects } from './effects';\nimport { initialMetadataState, metadataReducer } from './reducer';\nimport { MetadataToken } from './types';\nimport type { MetadataAction, MetadataCapability, MetadataState } from './types';\n\n/**\n * Document-scoped metadata plugin: reactive Info-dict state. The effect seeds it\n * from the engine and keeps it live off the document event stream (own + remote\n * SSE edits); the capability is the read/write surface.\n */\nexport const metadataPlugin = () =>\n  definePlugin<MetadataState, MetadataAction, MetadataCapability>({\n    id: 'metadata',\n    token: MetadataToken,\n    scope: 'document',\n    initialState: initialMetadataState,\n    reduce: metadataReducer,\n    capability: createMetadataCapability,\n    effects: registerMetadataEffects,\n  });\n"],"mappings":";;;;;;;;;;AAUA,MAAM,6BAA4C;;;;;;AAOlD,SAAgB,yBACd,KACoB;CACpB,MAAM,mBAAmB;EACvB,MAAM,MAAM,IAAI;EAChB,IAAI,CAAC,KAAK,MAAM,IAAI,MAAM,8BAA8B;EACxD,OAAO;CACT;CAEA,OAAO;EACL,UAAU;GAKR,OAAO,IAAI,KAAK,SAAS,OAAO,0BAA0B,KAAK;EACjE;EAEA,eAAe,IAAI,SAAS,CAAC,CAAC;EAE9B,QAAQ,OAAO,UAAU;GAGvB,MAAM,SAAS,MAAM,WAAW,CAAC,CAAC,SAAS,OAAO,KAAK;GACvD,IAAI,SAAS;IAAE,MAAM;IAAO,UAAU,OAAO;GAAS,CAAC;EACzD;EAEA,QAAQ,YAAY;GAClB,MAAM,WAAW,MAAM,WAAW,CAAC,CAAC,SAAS,KAAK;GAClD,IAAI,SAAS;IAAE,MAAM;IAAO;GAAS,CAAC;EACxC;CACF;AACF;;;;;;;;;;;;;;ACnCA,SAAgB,wBAAwB,KAAyD;CAC/F,MAAM,MAAM,IAAI;CAChB,IAAI,CAAC,KAAK;CAGV,IAAS,SAAS,KAAK,CAAC,CAAC,MACtB,aAAa,IAAI,SAAS;EAAE,MAAM;EAAO;CAAS,CAAC,SAC9C,CAAC,CACT;CAGA,MAAM,cAAc,IAAI,OAAO,WAAW,UAAyB;EACjE,IAAI,MAAM,SAAS,oBACjB,IAAI,SAAS;GAAE,MAAM;GAAO,UAAU,MAAM;EAAS,CAAC;CAE1D,CAAC;CACD,IAAI,QAAQ,WAAW;AACzB;;;AC7BA,MAAa,8BAA6C,EAAE,UAAU,KAAK;;;AAI3E,MAAa,mBAAmB,OAAsB,MACpD,EAAE,SAAS,QAAQ;CAAE,GAAG;CAAO,UAAU,EAAE;AAAS,IAAI;;;;;;;;ACK1D,MAAa,uBACX,aAAgE;CAC9D,IAAI;CACJ,OAAO;CACP,OAAO;CACP,cAAc;CACd,QAAQ;CACR,YAAY;CACZ,SAAS;AACX,CAAC"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/model.ts","../src/controller.ts","../src/metadata.plugin.ts","../src/state.ts"],"sourcesContent":["/**\n * The keys whose values differ between two snapshots, removed keys included.\n * Both snapshots (the standard fields, the custom keys) hold only strings,\n * `null` and enums, so a shallow compare is exact.\n */\nexport function changedKeys<T extends object>(\n  previous: T | null,\n  next: T,\n): readonly (keyof T & string)[] {\n  const keys = Object.keys(next) as (keyof T & string)[];\n  if (!previous) return keys;\n  const all = new Set([...(Object.keys(previous) as (keyof T & string)[]), ...keys]);\n  return [...all].filter((key) => previous[key] !== next[key]);\n}\n","import {\n  PluginError,\n  type PluginContext,\n  type CustomMetadata,\n  type DocCapability,\n  type DocumentMetadata,\n  type OperationOptions,\n} from '@embedpdf/core';\n\nimport type {\n  CustomMetadataCapability,\n  CustomMetadataResyncedEvent,\n  CustomMetadataUpdatedEvent,\n  MetadataCapability,\n  MetadataResyncedEvent,\n  MetadataUpdatedEvent,\n} from './contract';\nimport { changedKeys } from './model';\n\nconst METADATA_MODIFY: DocCapability = 'doc.metadata.modify';\n\n/**\n * The metadata controller. Both halves of the Info dict are mirrors: each\n * changes only when a load lands or its confirmed document event arrives\n * (`metadata.updated`, `metadata.customUpdated`), whoever caused the edit,\n * and that is also the one place its `onUpdated` and `onResynced` fire.\n * Nothing needs them when a document opens, so they load on demand: the\n * first `ensureLoaded()` (what `metadataState` asks for) reads them.\n */\nexport function createMetadataController(ctx: PluginContext<void>) {\n  const updated = ctx.events.source<MetadataUpdatedEvent>();\n  const resynced = ctx.events.source<MetadataResyncedEvent>();\n  const customUpdated = ctx.events.source<CustomMetadataUpdatedEvent>();\n  const customResynced = ctx.events.source<CustomMetadataResyncedEvent>();\n\n  const metadata = ctx.mirror<DocumentMetadata | null>({\n    name: 'metadata',\n    onDemand: true,\n    initial: () => null,\n    load: async (doc) => ({ value: await doc.metadata.get() }),\n    fold: (value, event) => (event.type === 'metadata.updated' ? event.metadata : value),\n    changed: ({ cause, event, previous, next }) => {\n      if (!next) return;\n      if (cause === 'load') {\n        resynced.emit({ metadata: next });\n      } else if (event && 'origin' in event) {\n        updated.emit({\n          metadata: next,\n          previous,\n          changedKeys: changedKeys(previous, next),\n          origin: event.origin,\n        });\n      }\n    },\n  });\n\n  const custom = ctx.mirror<CustomMetadata | null>({\n    name: 'customMetadata',\n    onDemand: true,\n    initial: () => null,\n    load: async (doc) => ({ value: await doc.metadata.custom.get() }),\n    fold: (value, event) => (event.type === 'metadata.customUpdated' ? event.custom : value),\n    changed: ({ cause, event, previous, next }) => {\n      if (!next) return;\n      if (cause === 'load') {\n        customResynced.emit({ custom: next });\n      } else if (event && 'origin' in event) {\n        customUpdated.emit({\n          custom: next,\n          previous,\n          changedKeys: changedKeys(previous, next),\n          origin: event.origin,\n        });\n      }\n    },\n  });\n\n  const canUpdate = () => ctx.allows(METADATA_MODIFY);\n\n  /**\n   * Both writes refuse the same way before reaching the engine: the verbs are\n   * async, so a refusal rejects, and nothing changes.\n   */\n  const refuseWrite = (verb: string, options?: OperationOptions): void => {\n    ctx.assertAllowed(METADATA_MODIFY, verb);\n    if (options?.signal?.aborted) {\n      throw new PluginError('operation-cancelled', 'metadata', `${verb} was cancelled`);\n    }\n  };\n\n  const customApi: CustomMetadataCapability = {\n    getSnapshot: custom.get,\n    getStatus: custom.getStatus,\n    update: async (patch, options) => {\n      refuseWrite('metadata.custom.update', options);\n      const result = await ctx.cancellable(options?.signal, ctx.doc.metadata.custom.update(patch));\n      return { custom: result.custom };\n    },\n    refresh: (options) => ctx.cancellable(options?.signal, custom.refresh()),\n    onUpdated: customUpdated.on,\n    onResynced: customResynced.on,\n  };\n\n  const api: MetadataCapability = {\n    getSnapshot: metadata.get,\n    getStatus: metadata.getStatus,\n    ensureLoaded: (options) =>\n      ctx.cancellable(\n        options?.signal,\n        Promise.all([metadata.ensureLoaded(), custom.ensureLoaded()]).then(() => undefined),\n      ),\n    canUpdate,\n    update: async (patch, options) => {\n      refuseWrite('metadata.update', options);\n      const result = await ctx.cancellable(options?.signal, ctx.doc.metadata.update(patch));\n      return { metadata: result.metadata };\n    },\n    refresh: (options) => ctx.cancellable(options?.signal, metadata.refresh()),\n    onUpdated: updated.on,\n    onResynced: resynced.on,\n    custom: customApi,\n  };\n\n  return { api };\n}\n","import { definePlugin } from '@embedpdf/core';\n\nimport { MetadataToken } from './contract';\nimport { createMetadataController } from './controller';\n\n/** Document-scoped, reactive Info-dict metadata. Takes no configuration. */\nexport const metadataPlugin = () =>\n  definePlugin({\n    id: 'metadata',\n    token: MetadataToken,\n    scope: 'document',\n    create: createMetadataController,\n  });\n","/**\n * The metadata page's State table as code: what `useMetadataState()` returns,\n * and the same fields in every other framework. `status` is the standard\n * fields' load state; `custom.getStatus()` has the custom keys' own. Reading\n * the state loads it (`ensure`): the first reader of a document starts the read.\n */\nimport { defineState } from '@embedpdf/core';\n\nimport { MetadataToken } from './contract';\n\nexport const metadataState = defineState(MetadataToken, {\n  read: (metadata) => ({\n    metadata: metadata.getSnapshot(),\n    custom: metadata.custom.getSnapshot(),\n    status: metadata.getStatus(),\n  }),\n  empty: {\n    metadata: null,\n    custom: null,\n    status: 'idle',\n  },\n  ensure: (metadata) => metadata.ensureLoaded(),\n});\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embedpdf/plugin-metadata",
-  "version": "3.0.0-next.14",
+  "version": "3.0.0-next.15",
   "private": false,
   "description": "Document-scoped metadata: reactive Info-dict state fed by the document event stream (own edits + remote SSE), with a three-state update that writes to the layer.",
   "type": "module",
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@embedpdf/core": "3.0.0-next.14"
+    "@embedpdf/core": "3.0.0-next.15"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/dist/contract-CqhcLHxo.cjs

@@ -1,11 +0,0 @@
-//#region src/types.ts
-const MetadataToken = (0, require("@embedpdf/core").createCapabilityToken)("metadata");
-//#endregion
-Object.defineProperty(exports, "MetadataToken", {
-	enumerable: true,
-	get: function() {
-		return MetadataToken;
-	}
-});
-
-//# sourceMappingURL=contract-CqhcLHxo.cjs.map

package/dist/contract-CqhcLHxo.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-CqhcLHxo.cjs","names":[],"sources":["../src/types.ts"],"sourcesContent":["import { createCapabilityToken, type DocumentMetadata, type MetadataPatch } from '@embedpdf/core';\n\n/**\n * The document's Info-dict metadata, held as REACTIVE state — not a one-shot\n * read. It changes from local edits AND from other sessions (a remote edit\n * arrives over SSE as a `metadata.updated` event), so the plugin subscribes to\n * the document event stream and keeps `current()` live. `update` writes a\n * three-state patch into the LAYER (like a page mutation), so a metadata edit\n * saves with the layer.\n */\nexport interface MetadataState {\n  /** Current metadata, or null until the first read resolves. */\n  metadata: DocumentMetadata | null;\n}\n\nexport type MetadataAction = { type: 'SET'; metadata: DocumentMetadata | null };\n\nexport interface MetadataCapability {\n  /**\n   * Whether this caller is authorized to edit the Info dict —\n   * `effectiveScope` includes `doc.metadata.modify` (PDF bit 4). UIs gate their\n   * edit affordances on this; the engine independently enforces the same\n   * capability and throws `PermissionDenied` if a write slips through.\n   */\n  canEdit(): boolean;\n  /** Current metadata; null until the initial read lands. Reactive — reflects\n   *  own edits and remote (SSE) edits via the event stream. */\n  current(): DocumentMetadata | null;\n  /** Patch the Info dict (undefined=leave, null=clear, value=set). Writes to the\n   *  layer; state refreshes from the resulting `metadata.updated` event. */\n  update(patch: MetadataPatch): Promise<void>;\n  /** Force a re-read from the engine (rarely needed — the event stream keeps\n   *  state fresh). */\n  reload(): Promise<void>;\n}\n\nexport const MetadataToken = createCapabilityToken<MetadataCapability>('metadata');\n"],"mappings":";AAoCA,MAAa,iBAAA,2BAAA,CAAA,CAAA,sBAAA,CAA0D,UAAU"}

package/dist/contract-DXGV7Wpx.js

@@ -1,7 +0,0 @@
-import { createCapabilityToken } from "@embedpdf/core";
-//#region src/types.ts
-const MetadataToken = createCapabilityToken("metadata");
-//#endregion
-export { MetadataToken as t };
-
-//# sourceMappingURL=contract-DXGV7Wpx.js.map

package/dist/contract-DXGV7Wpx.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"contract-DXGV7Wpx.js","names":[],"sources":["../src/types.ts"],"sourcesContent":["import { createCapabilityToken, type DocumentMetadata, type MetadataPatch } from '@embedpdf/core';\n\n/**\n * The document's Info-dict metadata, held as REACTIVE state — not a one-shot\n * read. It changes from local edits AND from other sessions (a remote edit\n * arrives over SSE as a `metadata.updated` event), so the plugin subscribes to\n * the document event stream and keeps `current()` live. `update` writes a\n * three-state patch into the LAYER (like a page mutation), so a metadata edit\n * saves with the layer.\n */\nexport interface MetadataState {\n  /** Current metadata, or null until the first read resolves. */\n  metadata: DocumentMetadata | null;\n}\n\nexport type MetadataAction = { type: 'SET'; metadata: DocumentMetadata | null };\n\nexport interface MetadataCapability {\n  /**\n   * Whether this caller is authorized to edit the Info dict —\n   * `effectiveScope` includes `doc.metadata.modify` (PDF bit 4). UIs gate their\n   * edit affordances on this; the engine independently enforces the same\n   * capability and throws `PermissionDenied` if a write slips through.\n   */\n  canEdit(): boolean;\n  /** Current metadata; null until the initial read lands. Reactive — reflects\n   *  own edits and remote (SSE) edits via the event stream. */\n  current(): DocumentMetadata | null;\n  /** Patch the Info dict (undefined=leave, null=clear, value=set). Writes to the\n   *  layer; state refreshes from the resulting `metadata.updated` event. */\n  update(patch: MetadataPatch): Promise<void>;\n  /** Force a re-read from the engine (rarely needed — the event stream keeps\n   *  state fresh). */\n  reload(): Promise<void>;\n}\n\nexport const MetadataToken = createCapabilityToken<MetadataCapability>('metadata');\n"],"mappings":";;AAoCA,MAAa,gBAAgB,sBAA0C,UAAU"}

package/dist/contract-Dk5SGhEP.d.cts

@@ -1,40 +0,0 @@
-import { DocumentMetadata, MetadataPatch } from "@embedpdf/core";
-//#region src/types.d.ts
-/**
- * The document's Info-dict metadata, held as REACTIVE state — not a one-shot
- * read. It changes from local edits AND from other sessions (a remote edit
- * arrives over SSE as a `metadata.updated` event), so the plugin subscribes to
- * the document event stream and keeps `current()` live. `update` writes a
- * three-state patch into the LAYER (like a page mutation), so a metadata edit
- * saves with the layer.
- */
-interface MetadataState {
-  /** Current metadata, or null until the first read resolves. */
-  metadata: DocumentMetadata | null;
-}
-type MetadataAction = {
-  type: 'SET';
-  metadata: DocumentMetadata | null;
-};
-interface MetadataCapability {
-  /**
-   * Whether this caller is authorized to edit the Info dict —
-   * `effectiveScope` includes `doc.metadata.modify` (PDF bit 4). UIs gate their
-   * edit affordances on this; the engine independently enforces the same
-   * capability and throws `PermissionDenied` if a write slips through.
-   */
-  canEdit(): boolean;
-  /** Current metadata; null until the initial read lands. Reactive — reflects
-   *  own edits and remote (SSE) edits via the event stream. */
-  current(): DocumentMetadata | null;
-  /** Patch the Info dict (undefined=leave, null=clear, value=set). Writes to the
-   *  layer; state refreshes from the resulting `metadata.updated` event. */
-  update(patch: MetadataPatch): Promise<void>;
-  /** Force a re-read from the engine (rarely needed — the event stream keeps
-   *  state fresh). */
-  reload(): Promise<void>;
-}
-declare const MetadataToken: import("@embedpdf/core").CapabilityToken<MetadataCapability>;
-//#endregion
-export { MetadataToken as i, MetadataCapability as n, MetadataState as r, MetadataAction as t };
-//# sourceMappingURL=contract-Dk5SGhEP.d.cts.map

package/dist/contract-Dk5SGhEP.d.ts

@@ -1,40 +0,0 @@
-import { DocumentMetadata, MetadataPatch } from "@embedpdf/core";
-//#region src/types.d.ts
-/**
- * The document's Info-dict metadata, held as REACTIVE state — not a one-shot
- * read. It changes from local edits AND from other sessions (a remote edit
- * arrives over SSE as a `metadata.updated` event), so the plugin subscribes to
- * the document event stream and keeps `current()` live. `update` writes a
- * three-state patch into the LAYER (like a page mutation), so a metadata edit
- * saves with the layer.
- */
-interface MetadataState {
-  /** Current metadata, or null until the first read resolves. */
-  metadata: DocumentMetadata | null;
-}
-type MetadataAction = {
-  type: 'SET';
-  metadata: DocumentMetadata | null;
-};
-interface MetadataCapability {
-  /**
-   * Whether this caller is authorized to edit the Info dict —
-   * `effectiveScope` includes `doc.metadata.modify` (PDF bit 4). UIs gate their
-   * edit affordances on this; the engine independently enforces the same
-   * capability and throws `PermissionDenied` if a write slips through.
-   */
-  canEdit(): boolean;
-  /** Current metadata; null until the initial read lands. Reactive — reflects
-   *  own edits and remote (SSE) edits via the event stream. */
-  current(): DocumentMetadata | null;
-  /** Patch the Info dict (undefined=leave, null=clear, value=set). Writes to the
-   *  layer; state refreshes from the resulting `metadata.updated` event. */
-  update(patch: MetadataPatch): Promise<void>;
-  /** Force a re-read from the engine (rarely needed — the event stream keeps
-   *  state fresh). */
-  reload(): Promise<void>;
-}
-declare const MetadataToken: import("@embedpdf/core").CapabilityToken<MetadataCapability>;
-//#endregion
-export { MetadataToken as i, MetadataCapability as n, MetadataState as r, MetadataAction as t };
-//# sourceMappingURL=contract-Dk5SGhEP.d.ts.map