@paged-media/plugin-api 0.2.33-canary.0 → 0.2.35-canary.0

package/dist/host.d.ts

@@ -1235,6 +1235,40 @@ export interface DiagnosticsSurface {
     get(key: string): Diagnostic[];
     onDidChange(listener: (key: string) => void): Disposable;
 }
+/** One entry a bundle contributes to the host's journal.
+ *
+ *  The host stamps `plugin`, `seq`, `t` and `origin` — a bundle cannot forge
+ *  attribution, the same provenance rule `contribute.panel` already applies. */
+export interface JournalRecord {
+    /** Dotted, and MUST be namespaced under the manifest id — the same
+     *  chokepoint as every other contribution id, so an entry is always
+     *  attributable. e.g. `media.paged.draw.boolean.union`. */
+    code: string;
+    severity?: "debug" | "info" | "warn" | "error";
+    durMs?: number;
+    /** Bounded scalars. String values MUST match
+     *  `/^[a-z0-9][a-z0-9._:-]{0,63}$/` — a sentence, a file path, a font
+     *  family or any user text CANNOT pass, BY DESIGN. There is deliberately no
+     *  free-text field anywhere on this type: that is the field through which
+     *  PII leaks in every telemetry system ever built. A rejected value is
+     *  dropped and COUNTED, never silently truncated (a truncated path is still
+     *  a path). Keep the human sentence in `host.log`, which goes to the
+     *  console and is not part of any exported artifact. */
+    data?: Record<string, number | boolean | string>;
+}
+/** The JOURNAL door — a local, in-memory flight recorder.
+ *
+ *  With no host buffer wired this surface is INERT and
+ *  `supports("journal@1")` is false. That means "recording goes nowhere",
+ *  never "calling this throws": an instrumentation door that can break the
+ *  plugin it instruments is worse than no door. */
+export interface JournalSurface {
+    record(entry: JournalRecord): void;
+    /** Time a thunk (sync or async) and record one entry carrying `durMs` and
+     *  `data.ok`. The thunk's own result and exceptions pass through unchanged
+     *  — instrumenting a call must not alter what it returns or hide a throw. */
+    time<T>(code: string, fn: () => T | Promise<T>): Promise<T>;
+}
 export interface BindingsSurface {
     /** Publish (or update) a named reactive value. Schema rows reading
      *  `{ bind: name }` re-render on every change. JSON only. */
@@ -1310,6 +1344,9 @@ export interface BundleHost {
      *  `supports("dataProviders@1")` is false (the honest no-registry posture). */
     readonly dataProviders: DataProvidersSurface;
     readonly diagnostics: DiagnosticsSurface;
+    /** ADR 025 — the local flight recorder. Probe `supports("journal@1")`
+     *  before relying on it reaching a buffer; calling it is always safe. */
+    readonly journal: JournalSurface;
     /** Published reactive values (W3.1) — the dynamic half of schema
      *  panels: a bundle publishes named booleans (and JSON values) that
      *  schema rows reference for `visible`/`enabled`. The plugin owns the

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type { PluginId, PluginManifest, PluginCapabilities, PluginContributions, NetworkCapability, DataProvidersCapability, StorageCapability, WasmArtifact, WasmPurpose, WorkersCapability, SecretsCapability, GpuCapability, } from "./manifest";
 export type { BundleHandle, PagedBundle } from "./bundle";
-export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, MenuContribution, } from "./host";
+export type { BundleHost, ContributionSurface, SceneLayerSurface, ImagesSurface, ImageResourceClaimOptions, TileBytes, WorkersSurface, BundleWorker, SpawnWorkerOptions, SecretsSurface, SecretMaterial, DocumentSurface, SelectionSurface, ViewportSurface, TextSurface, TextMetrics, TextCaret, FrameChainLink, PlanarFace, PlanarRegionsResult, StoryContent, ParagraphContent, RunContent, OverlaySurface, ShellSurface, FilePickerOptions, PickedFile, SaveFileOptions, StorageSurface, BlobSurface, BlobUsage, PartsSurface, NativeDocumentSurface, NetworkSurface, ConsentResult, DataProvidersSurface, DataProviderRegistration, DataProviderHandle, DataProviderInfo, DataProviderSnapshot, ProviderSchema, ProviderField, ProviderRecordSet, DiagnosticsSurface, JournalSurface, JournalRecord, BindingsSurface, Diagnostic, DocumentChangeEvent, MutationOutcome, Disposable, PluginLogger, EditContextContribution, ObjectTypeContribution, EditContextCandidate, EnteredEditContext, ContentPointerEvent, EditContextDescriptor, ObjectTypeDescriptor, PluginMetadataEnvelope, ObjectTypeBaker, BakeContext, MenuContribution, } from "./host";
 export type { PanelSchema, PanelSchemaSection, PanelSchemaRow, SchemaPanelContribution, SchemaPanelRenderer, SchemaPanelRendererProps, WidgetValueBinding, BindingRef, SchemaGate, WidgetCollectionBinding, SchemaRowAction, SchemaListAction, SchemaListSpec, } from "./panel-schema";
 export type { WidgetSurface, CodeEditorProps, CodeEditorDiagnostic, CodeEditorLanguage, } from "./widgets";
 export type { BindingTarget, BindingPropertyRequest, BindingPropertyWrite, BindingCollectionRequest, BindingRead, BindingResolved, BindingDecline, BindingWrite, BindingCollection, BindingOp, BindingProvider, BindingProviderScope, BindingProviderHandle, BindingReadResult, BindingWriteResult, BindingCollectionResult, ActiveBindingProvider, } from "./binding-provider";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paged-media/plugin-api",
-  "version": "0.2.33-canary.0",
+  "version": "0.2.35-canary.0",
   "description": "The Paged plugin contract: manifest, bundle lifecycle, the BundleHost surface, and the contribution + engine wire types. Type-only.",
   "license": "MPL-2.0 OR LicenseRef-PMEL",
   "type": "module",