@belonguniverseai/react-sdk 0.6.20 → 0.6.22

package/dist/embed/client-error-log.d.ts

@@ -0,0 +1,72 @@
+/**
+ * A bounded tail of what already went wrong in this browser tab, so an issue
+ * report can carry it (issue-report-open.ts reads this).
+ *
+ * This is the ONE input to a report that is unrecoverable after the fact: a
+ * render that threw or a 500 on a dock route leaves no server-side trace tied
+ * to the user's complaint.
+ *
+ * Deliberately narrow: kind, a truncated message, and for a request failure
+ * the route and status. We never read a response body into this buffer
+ * ourselves — our own failures (`reportClientError`'s call sites) record a
+ * route and a status code, never the body. But the two global listeners
+ * below capture host-authored error text verbatim, and a host application
+ * can legally do `throw new Error(await response.text())` — at that point
+ * the "message" a window `error`/`unhandledrejection` event carries IS a
+ * response body, word for word. There is no way to strip that out without
+ * inspecting arbitrary Error objects we cannot parse, so the mitigation is a
+ * hard cap: host-originated text gets
+ * `MAX_HOST_CLIENT_ERROR_MESSAGE_CHARS` (120), well short of a useful
+ * response body, while our own controlled messages keep the full
+ * `MAX_CLIENT_ERROR_MESSAGE_CHARS` (500). See `recordClientError` vs.
+ * `recordHostClientError` below.
+ *
+ * Module-level store in the same grain as approval-bus.ts: one per page, no
+ * React, readable from anywhere in the dock.
+ */
+export declare const MAX_CLIENT_ERROR_ENTRIES = 20;
+/**
+ * Cap for a message recorded through the CONTROLLED path — our own
+ * `reportClientError` call sites (`api/report-client-error.ts`). We author
+ * that text ourselves (a fixed set of transport-failure kinds), so it is
+ * known-safe at the full length.
+ */
+export declare const MAX_CLIENT_ERROR_MESSAGE_CHARS = 500;
+/**
+ * Cap for a message recorded through the UNCONTROLLED path — the global
+ * `window` `error` / `unhandledrejection` listeners below. That text is
+ * authored by the HOST PAGE, not by us: a host that does
+ * `throw new Error(await response.text())` hands its rejection message
+ * straight to `onRejection`, and without a hard cap a response body would
+ * ride into the next issue report intact. Kept far below the controlled cap
+ * on purpose — this is a privacy boundary, not a display truncation.
+ */
+export declare const MAX_HOST_CLIENT_ERROR_MESSAGE_CHARS = 120;
+export type ClientErrorEntry = {
+    readonly at: string;
+    readonly kind: string;
+    readonly message: string;
+    readonly route?: string;
+    readonly status?: number;
+};
+type ClientErrorInput = {
+    readonly kind: string;
+    readonly message: string;
+    readonly route?: string;
+    readonly status?: number;
+    readonly at?: string;
+};
+/**
+ * Record an error from the CONTROLLED path: our own `reportClientError` call
+ * sites. Gets the full `MAX_CLIENT_ERROR_MESSAGE_CHARS` cap — see that
+ * constant's doc comment for why the two paths are capped differently.
+ */
+export declare const recordClientError: (entry: ClientErrorInput) => void;
+export declare const peekClientErrors: () => readonly ClientErrorEntry[];
+/**
+ * Subscribe to uncaught errors and unhandled rejections. Returns the
+ * uninstaller; safe to call more than once (each call returns its own).
+ */
+export declare const installGlobalClientErrorCapture: (target: Window) => (() => void);
+export declare const __resetClientErrorLogForTest: () => void;
+export {};

package/dist/embed/copy.d.ts

@@ -105,6 +105,7 @@ export type DockCopy = {
         readonly english: string;
         readonly spanish: string;
         readonly portuguese: string;
+        readonly italian: string;
     };
     readonly menu: MenuCopy;
     /** One line of scope in the user's own nouns (spec 2026-09-03). */

package/dist/embed/dev-mode.d.ts

@@ -16,11 +16,12 @@ export type AgentRuntime = (typeof AGENT_RUNTIMES)[number];
 /**
  * LLM providers the dev panel can swap the model to. Honored by the MASTRA
  * runtime only (its model resolves per turn); the other runtimes own their
- * model wiring and ignore the override. `gateway` is the generic router
+ * model wiring and ignore the override. Production requires the worker's
+ * ALLOW_MODEL_OVERRIDES opt-in. `gateway` is the generic router
  * (Vercel AI Gateway): pair it with a free-typed `provider/model` slug
  * (e.g. `deepseek/deepseek-v4-pro`) to reach any model the gateway serves.
  */
-export declare const LLM_PROVIDERS: readonly ["anthropic", "google", "openai", "cerebras", "gateway", "openrouter"];
+export declare const LLM_PROVIDERS: readonly ["anthropic", "google", "openai", "cerebras", "gateway", "openrouter", "vertex"];
 export type LlmProvider = (typeof LLM_PROVIDERS)[number];
 /**
  * A free-typed model id must be safe to ride the wire verbatim: bounded, no
@@ -37,11 +38,8 @@ export type LlmProvider = (typeof LLM_PROVIDERS)[number];
  * `claude-haiku-4-5@20251001`, `vertex`'s own `DEFAULT_MODEL_IDS` value in
  * llm-model-resolver.ts) — this dev panel is the one UI that free-types a
  * model id, so a charset drift here is the one that actually blocks a live
- * smoke rather than just failing a schema test. NOTE: `LLM_PROVIDERS` above
- * does not include "vertex" yet (mirrored by the transport's `llmProvider`
- * enum) — the dev panel cannot *select* vertex as a provider, so this
- * free-typed model id is the only path that reaches it today; a future
- * vertex-enum PR must update both this file and the transport together.
+ * smoke rather than just failing a schema test. The transport's provider enum
+ * must also accept every provider selectable here, including Vertex.
  */
 export declare const isValidLlmModelId: (value: string) => boolean;
 /** True when the typed text is the cheat code (trim + case-insensitive). */

package/dist/embed/dock-open-request.d.ts

@@ -0,0 +1,32 @@
+import { DockResizeState } from './dock-layout.ts';
+type DockOpenSize = "expanded" | "fullscreen";
+/** A pending size: an explicit one, or `default` = `open()` with no size. */
+type PendingDockSize = DockOpenSize | "default";
+/** The public `BelongOpenOptions.draft` ceiling. */
+export declare const DOCK_OPEN_DRAFT_MAX_CHARS = 4000;
+/**
+ * Record a host open request and notify the dock. Parsed at the host boundary
+ * (§4): an invalid request is ignored with one console warning — never a throw
+ * into the host page. A request without a draft leaves a still-pending draft
+ * in place (it did not ask to cancel it); a newer draft replaces it.
+ */
+export declare const requestDockOpen: (options: unknown) => void;
+/** The pending size WITHOUT consuming it — for render-time initializers. */
+export declare const peekPendingDockSize: () => PendingDockSize | null;
+/** Consume the pending size: returned once, then null. */
+export declare const takePendingDockSize: () => PendingDockSize | null;
+/** Consume the pending draft: returned once, then null. */
+export declare const takePendingDockDraft: () => string | null;
+/** Notified once per accepted request; returns an unsubscribe. */
+export declare const subscribeDockOpenRequest: (listener: () => void) => (() => void);
+/**
+ * The size a request resolves to from the dock's current one. `default` shows
+ * the dock without changing an open size (a collapsed dock opens); an explicit
+ * size wins. Fullscreen is a desktop size: on a phone the open sheet already
+ * fills the viewport, so it resolves to `expanded` — the same rule the dock's
+ * initializer applies to a persisted fullscreen.
+ */
+export declare const resolveRequestedDockSize: (requested: PendingDockSize, current: DockResizeState, mobile: boolean) => DockResizeState;
+/** Test-only: nothing pending, no subscribers. */
+export declare const __resetDockOpenRequestForTest: () => void;
+export {};

package/dist/embed/dock-state.d.ts

@@ -5,7 +5,7 @@
  * in the stream-state store; this module owns only view + size. Best-effort:
  * disabled/quota'd storage just means no cross-reload restore.
  */
-export type DockView = "chat" | "files" | "scheduled" | "prompts" | "connectors";
+export type DockView = "chat" | "goal" | "files" | "scheduled" | "prompts" | "connectors" | "skills";
 export type DockSize = "collapsed" | "expanded" | "fullscreen";
 export type DockState = {
     readonly view: DockView;

package/dist/embed/goal-actions-model.d.ts

@@ -0,0 +1,9 @@
+import { GoalStatus } from '../api/goals.ts';
+export type GoalActionAvailability = {
+    readonly pause: boolean;
+    readonly resume: boolean;
+    readonly wake: boolean;
+    readonly snooze: boolean;
+    readonly clear: boolean;
+};
+export declare const goalActionAvailability: (status: GoalStatus) => GoalActionAvailability;

package/dist/embed/goal-cap-notice.d.ts

@@ -0,0 +1,36 @@
+import { PostMessageError } from '../stream/belong-chat-transport.ts';
+export type GoalRefusal = {
+    readonly kind: "exists";
+} | {
+    readonly kind: "disabled";
+} | {
+    readonly kind: "cap_user";
+    readonly limit: number;
+} | {
+    readonly kind: "cap_tenant";
+} | {
+    readonly kind: "plan_mode";
+} | {
+    readonly kind: "not_sent";
+};
+/**
+ * Classify a refused `goal` send. `null` when the error is not a goal
+ * refusal at all — the caller's existing stream-error path still owns that.
+ *
+ * A non-`PostMessageError` means the send never reached the server (a
+ * network failure, an aborted fetch, …) — that is always `not_sent`,
+ * whatever the JS error happens to be, because the caller only classifies
+ * failures of a send IT started (see `handleCreateSendError` in
+ * `use-session-goal.ts`). A `PostMessageError` whose status/body the server
+ * never documented for `/goal` (a 500 `run_failed`, say) is left to the
+ * chat's own generic error surface instead of being misread as a refusal.
+ */
+export declare const goalRefusalFromError: (error: unknown) => GoalRefusal | null;
+/**
+ * A refused POST, whatever the reason. `PostMessageError.message` embeds the
+ * server's status AND its raw body (a wire enum, untranslated English prose,
+ * or a Zod issue list) — never show that to a user: the dock renders its own
+ * i18n'd fallback instead. The memory note "server prose isn't localized" is
+ * exactly this failure, and §42's "reads as breakage" is the cost.
+ */
+export declare const isPostMessageRefusal: (error: unknown) => error is PostMessageError;

package/dist/embed/goal-deep-link.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Ruling 4's exact contract (spec §4/§9) — a goal-transition email carries a
+ * button back into the dock: `<base>?belongSession=<id>&belongView=goal`
+ * (`goalDeepLinkUrl` on the cloud side builds it; this reads it). Two rules:
+ * the param names are `belongSession` and `belongView` — a typo on either
+ * side is a link that silently does nothing — and the params are STRIPPED
+ * once read, so a reload of the dock does not yank the user back into a
+ * goal they have already looked at.
+ *
+ * `view` is accepted ONLY when it is exactly `"goal"` — no other value is a
+ * link this reader recognizes — so `GoalDeepLink` can carry the literal type
+ * rather than a wider `EmbedView`, and a caller never has to re-check it.
+ * Any other combination (missing `belongSession`, missing/mismatched
+ * `belongView`, or no params at all) returns `null` and leaves the query
+ * string untouched — a page whose query string was never ours to rewrite.
+ */
+export type GoalDeepLink = {
+    readonly sessionId: string;
+    readonly view: "goal";
+};
+export declare const consumeGoalDeepLink: (location: {
+    readonly search: string;
+    readonly replaceSearch: (next: string) => void;
+}) => GoalDeepLink | null;

package/dist/embed/goal-edit-command.d.ts

@@ -0,0 +1,25 @@
+import { GoalActionOutcome, GoalEditInput } from '../api/goals.ts';
+import { BuiltinCommand } from './slash-commands.ts';
+/** The three `/goal` sub-commands that map onto `POST .../goal/edit`. */
+type GoalEditCommand = Extract<BuiltinCommand, {
+    readonly action: "edit";
+} | {
+    readonly action: "turns";
+} | {
+    readonly action: "budget";
+}>;
+/** `editSessionGoal`'s full outcome union, including the client-only
+ *  `"no_change"` case (`api/goals.ts`'s 400 `goal_edit_no_change` mapping). */
+type GoalEditOutcome = GoalActionOutcome | {
+    readonly status: "no_change";
+};
+type GoalEditNoticeKey = "goal.revived" | "goal.edited" | "goal.notEditable" | "goal.editUsage" | "goal.none" | "goal.disabled" | "goal.error";
+/** Command → `POST .../goal/edit` request body. */
+export declare const goalEditRequestBody: (command: GoalEditCommand) => GoalEditInput;
+/**
+ * `editSessionGoal` outcome → the i18n key for the local notice. A `revived`
+ * edit (a raised cap that un-stalled a `budget_limited` goal) gets its own
+ * copy distinct from a plain edit — see `GoalActionOutcome`'s `revived` flag.
+ */
+export declare const goalEditNoticeKey: (outcome: GoalEditOutcome) => GoalEditNoticeKey;
+export {};

package/dist/embed/goal-journal.d.ts

@@ -0,0 +1,53 @@
+import { GoalJournalEntry } from '../api/goals.ts';
+/**
+ * A status change is named by the status it reached — the dock already has
+ * localized words for all twelve, and "blocked" tells the reader more than
+ * "transition" ever could. Everything else is named by its kind.
+ *
+ * `deferred` is the one exception (final review, Medium 2). `statusLabel`
+ * words are written for the PILL, where they answer "what is this goal doing
+ * right now": "waiting for a time" is right there and wrong in a history,
+ * where each line is something that HAPPENED at a named moment — and, since
+ * `/goal snooze` now writes no note, that label would be the whole line.
+ * The kind's own "Went to sleep" reads as an event, which is what the
+ * timeline is made of.
+ */
+export declare const goalJournalLabelKey: (entry: GoalJournalEntry) => string;
+/**
+ * An entry earns a line when it SAYS something: it changed the status, or it
+ * carries a note. A bare accounting row (kind `turn`, no note, no status
+ * move) is bookkeeping — putting it in History would push the things that
+ * actually happened out of a ten-row window.
+ */
+export declare const visibleGoalJournal: (journal: readonly GoalJournalEntry[] | undefined) => readonly GoalJournalEntry[];
+export type GoalJournalDay = {
+    readonly key: string;
+    readonly entries: readonly GoalJournalEntry[];
+};
+/**
+ * Local calendar day key (yyyy-mm-dd) for `date`, in the VIEWER's zone —
+ * not `toISOString()`, which is UTC and would put a 21:00 local entry on
+ * tomorrow's list for half the world. Shared by `groupGoalJournalByDay` and
+ * `isYesterdayKey` so both use one definition of "day".
+ */
+export declare const goalDayKey: (date: Date) => string;
+/**
+ * True when `dayKey` (as produced by `goalDayKey`) names the calendar day
+ * immediately before `now`'s day, in the viewer's zone. Backs the
+ * Timeline's "Yesterday" heading (appendix B "Timeline": `Today`,
+ * `Yesterday`, `Sep 12`). Walks `now` back one calendar day via the `Date`
+ * constructor's day-of-month rollover rather than subtracting 24h of
+ * milliseconds, so a DST-transition day still lands on the correct date.
+ */
+export declare const isYesterdayKey: (dayKey: string, now: Date) => boolean;
+/**
+ * Day buckets for the History timeline (appendix B "Timeline"), computed in
+ * the VIEWER's zone — the reader's "today" is the only one that matters, and
+ * the server's midnight is not it. `now` is injected (§25) so "Today" is
+ * testable.
+ *
+ * An entry whose `at` will not parse keeps its place in the list rather than
+ * disappearing: losing a line of history to a bad timestamp is a §41 loss,
+ * and the label is the load-bearing half of the row anyway.
+ */
+export declare const groupGoalJournalByDay: (entries: readonly GoalJournalEntry[], now: Date) => readonly GoalJournalDay[];

package/dist/embed/goal-live-status.d.ts

@@ -0,0 +1,2 @@
+import { GoalStatus } from '../api/goals.ts';
+export declare const isLiveGoalStatus: (status: GoalStatus) => boolean;

package/dist/embed/goal-plain-units.d.ts

@@ -0,0 +1,35 @@
+import { GoalView } from '../api/goals.ts';
+export type GoalElapsed = {
+    readonly kind: "just_started";
+} | {
+    readonly kind: "minutes";
+    readonly minutes: number;
+} | {
+    readonly kind: "hours";
+    readonly hours: number;
+    readonly minutes: number;
+} | {
+    readonly kind: "days";
+    readonly days: number;
+};
+export declare const goalElapsed: (input: {
+    readonly startedAt: string | null | undefined;
+    readonly now: Date;
+}) => GoalElapsed | null;
+/** Turns left, but only once the cap is close enough that the number changes
+ *  what the reader does about it. `null` otherwise, and `null` for a cap of
+ *  zero (never a division by it — §10). */
+export declare const goalTurnsRemaining: (goal: Pick<GoalView, "turnsUsed" | "maxTurns">) => number | null;
+/**
+ * The runway's plain numbers read straight off the goal's OWN stored caps,
+ * never a preset name — task-15 review, Low 4. `GoalSetCard` used to fall
+ * back to `runway ?? "normal"` for a pre-0071 row (`runway: null`), which
+ * labeled a goal that actually carries the Long preset's numbers as "Normal".
+ * When there is no preset to name honestly, describe the ACTUAL caps in the
+ * same steps-and-days vocabulary `goal-runway.ts`'s preset copy uses (spec
+ * ruling 1) instead of claiming a preset the row doesn't carry.
+ */
+export declare const goalRunwayPlain: (goal: Pick<GoalView, "maxTurns" | "maxActiveSeconds">) => {
+    readonly steps: number;
+    readonly days: number;
+};

package/dist/embed/goal-progress.d.ts

@@ -0,0 +1,15 @@
+import { GoalView } from '../api/goals.ts';
+export type GoalProgressModel = {
+    readonly percent: number;
+    readonly band: "barely" | "normal" | "almost_out";
+    readonly turnsUsed: number;
+    readonly maxTurns: number;
+    readonly runningSeconds: number;
+    readonly exact: {
+        readonly tokensUsed: number;
+        readonly tokenBudget: number;
+        readonly activeSeconds: number;
+        readonly maxActiveSeconds: number;
+    };
+};
+export declare const goalProgressModel: (goal: GoalView) => GoalProgressModel;

package/dist/embed/goal-proposal-dismissal.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ruling 5 (spec §7) — "Not now" on the proposal card, persisted per device.
+ * localStorage only for v1: a server-side dismissal marker is a later slice
+ * (spec "Not in this design"), so a reload on ANOTHER device shows the offer
+ * again — documented, acceptable. Every read/write is wrapped in try/catch:
+ * a private window throws on `localStorage` access, and this must never be
+ * the thing that breaks the card.
+ */
+export declare const goalProposalDismissalKey: (sessionId: string) => string;
+export declare const readGoalProposalDismissed: (sessionId: string) => boolean;
+export declare const writeGoalProposalDismissed: (sessionId: string) => void;

package/dist/embed/goal-resume-time.d.ts

@@ -0,0 +1,22 @@
+/**
+ * "resumes 09:00" — the goal pill's one piece of copy built from a time
+ * rather than a status key (`goal-status-label.ts`).
+ *
+ * Formatted in the VIEWER's locale and timezone, client-side, from the
+ * UTC instant the backend sends: the person reading the pill is the person
+ * who has to know whether 09:00 has happened yet, and a server-rendered
+ * time would be in the server's zone. `now` is a parameter rather than a
+ * `new Date()` inside (CLAUDE.md §25 — do not hide time), which is also
+ * what makes the same-day branch testable.
+ *
+ * Same day → the time alone ("09:00"); any other day → date and time
+ * ("Sep 12, 09:00"), because "09:00" on its own reads as *this morning*
+ * and a goal that is asleep until tomorrow is exactly the case where that
+ * misreads. Null for a missing or unparsable instant — the caller falls
+ * back to the plain "scheduled" label rather than rendering "Invalid Date".
+ */
+export declare const formatGoalResumeTime: (input: {
+    readonly resumeAt: string | null | undefined;
+    readonly now: Date;
+    readonly locale: string;
+}) => string | null;

package/dist/embed/goal-row-model.d.ts

@@ -0,0 +1,27 @@
+import { GoalElapsed } from './goal-plain-units.ts';
+import { GoalView } from '../api/goals.ts';
+export type GoalRowTone = "live" | "calm" | "attention";
+export type GoalRowActionKind = "cancel_setup" | "pause" | "resume" | "wake_now" | "details" | "answer" | "review" | "show_me" | "tell_it" | "give_it_more" | "new_goal";
+export type GoalRowAction = {
+    readonly kind: GoalRowActionKind;
+    readonly labelKey: string;
+};
+export type GoalRowCopy = {
+    readonly key: string;
+    readonly vars?: Readonly<Record<string, string | number>>;
+};
+export type GoalRowModel = {
+    readonly tone: GoalRowTone;
+    readonly headline: GoalRowCopy;
+    readonly detail: GoalRowCopy | null;
+    /** Non-null only where the row shows a clock (working, checking, paused).
+     *  The component renders it through `goal.units.*` and passes the result
+     *  into `detail.vars` as `elapsed`. */
+    readonly elapsed: GoalElapsed | null;
+    /** Non-null ONLY for `deferred`. The component formats it in the viewer's
+     *  zone and passes it into `headline.vars` as `time`. */
+    readonly resumeAt: string | null;
+    readonly primary: GoalRowAction | null;
+    readonly secondary: GoalRowAction | null;
+};
+export declare const goalRowModel: (goal: GoalView, now: Date) => GoalRowModel | null;

package/dist/embed/goal-runway.d.ts

@@ -0,0 +1,5 @@
+export type GoalRunwayPreset = "quick" | "normal" | "long";
+export type GoalRunwayLabelKey = "goal.compose.runwayQuick" | "goal.compose.runwayNormal" | "goal.compose.runwayLong";
+export type GoalRunwayDetailKey = "goal.compose.runwayQuickDetail" | "goal.compose.runwayNormalDetail" | "goal.compose.runwayLongDetail";
+export declare const goalRunwayLabelKey: (preset: GoalRunwayPreset) => GoalRunwayLabelKey;
+export declare const goalRunwayDetailKey: (preset: GoalRunwayPreset) => GoalRunwayDetailKey;

package/dist/embed/goal-schedule-handoff.d.ts

@@ -0,0 +1,12 @@
+export declare const goalScheduleCommand: (objective: string) => string;
+/**
+ * The i18n key naming the cadence this objective's own words imply, or null
+ * when they imply none (final review, Low 5: spec §5 asks the ending's button
+ * to say "Run this again {{cadence}}", and the flat "on a schedule" never
+ * named the cadence `goalScheduleCommand` had already guessed).
+ *
+ * A KEY, not the `phrase` above: the phrase is the `/schedule` parser's own
+ * English input and must stay English, while the button is read by a user in
+ * their own language.
+ */
+export declare const goalScheduleCadenceKey: (objective: string) => string | null;

package/dist/embed/goal-status-label.d.ts

@@ -0,0 +1,3 @@
+import { GoalStatus } from '../api/goals.ts';
+export type GoalStatusLabelKey = "goal.statusLabel.clarifying" | "goal.statusLabel.active" | "goal.statusLabel.completionClaimed" | "goal.statusLabel.paused" | "goal.statusLabel.deferred" | "goal.statusLabel.waitingForUser" | "goal.statusLabel.waitingForApproval" | "goal.statusLabel.waitingForUiAction" | "goal.statusLabel.blocked" | "goal.statusLabel.budgetLimited" | "goal.statusLabel.complete" | "goal.statusLabel.cleared";
+export declare const goalStatusLabelKey: (status: GoalStatus) => GoalStatusLabelKey;

package/dist/embed/goal-time-usage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `GoalBadge`'s time-usage line, pulled out to a pure helper (task-9 review,
+ * finding 4). The prior version always rendered `Math.round(seconds / 60)`
+ * minutes, which read as "130 of 10080 min" for a week-long cap — CLAUDE.md
+ * §11 asks for human units, not a five-digit minute count.
+ *
+ * Rule: minutes when the cap is under 60 minutes, hours when the cap is
+ * under 48 hours, else days — chosen from the CAP so `used`/`max` always
+ * share one unit ("2 of 10 h", never "90 min of 10 h"). Both values round
+ * to integers in that unit; the caller (`GoalBadge.tsx`) applies
+ * `toLocaleString()` for large counts, same as the tokens line.
+ */
+export type GoalTimeUnit = "min" | "h" | "d";
+export type GoalTimeUsage = {
+    readonly used: number;
+    readonly max: number;
+    readonly unit: GoalTimeUnit;
+};
+export declare const formatGoalTimeUsage: (activeSeconds: number, maxActiveSeconds: number) => GoalTimeUsage;

package/dist/embed/issue-report-bus.d.ts

@@ -0,0 +1,14 @@
+import { CapturedScreenshot } from './screen-capture.ts';
+import { IssueReportClientContext } from './issue-report.ts';
+import { ClientErrorEntry } from './client-error-log.ts';
+export type IssueReportRequest = {
+    readonly sessionId: string | null;
+    readonly taskId: string | null;
+    readonly screenshot: CapturedScreenshot | null;
+    readonly context: IssueReportClientContext;
+    readonly clientErrors: readonly ClientErrorEntry[];
+};
+export declare const openIssueReport: (request: IssueReportRequest) => void;
+export declare const closeIssueReport: () => void;
+export declare const peekIssueReport: () => IssueReportRequest | null;
+export declare const subscribeIssueReport: (listener: () => void) => (() => void);

package/dist/embed/issue-report-open.d.ts

@@ -0,0 +1,8 @@
+import { captureScreen } from './screen-capture.ts';
+import { DockView } from './dock-state.ts';
+export declare const requestIssueReport: (input: {
+    readonly dockView: DockView;
+    readonly taskId?: string | null;
+    /** Injected in tests. */
+    readonly capture?: typeof captureScreen;
+}) => Promise<void>;

package/dist/embed/issue-report.d.ts

@@ -0,0 +1,41 @@
+import { DockView } from './dock-state.ts';
+/**
+ * The server's own caps (`apps/belong-cloud/src/features/issue-reports/issue-report.schemas.ts`,
+ * `hostUrl`/`userAgent`), mirrored here so a page with a long URL or an
+ * unusual user agent string never produces a report the route refuses with
+ * `invalid_meta`. Without this, the ONE feature whose job is catching the
+ * unreportable becomes the thing that cannot be reported: the SDK collapses
+ * that 400 to `request_failed` and the dialog says "Try again," which never
+ * succeeds for that user.
+ */
+export declare const MAX_HOST_URL_CHARS = 2000;
+export declare const MAX_USER_AGENT_CHARS = 500;
+export type IssueReportViewport = {
+    readonly widthPx: number;
+    readonly heightPx: number;
+    /** Device pixel ratio x100 — an integer, per §11. */
+    readonly dprX100: number;
+};
+export type IssueReportClientContext = {
+    readonly hostUrl: string;
+    readonly dockView: DockView;
+    readonly sdkVersion: string;
+    readonly sdkBuiltAt: string | null;
+    readonly viewport: IssueReportViewport;
+    readonly locale: string;
+    readonly userAgent: string;
+    readonly capturedAt: string;
+};
+export declare const readViewport: (win: {
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+    readonly devicePixelRatio: number;
+}) => IssueReportViewport;
+export declare const buildIssueReportContext: (input: {
+    readonly dockView: DockView;
+    readonly hostUrl: string;
+    readonly locale: string;
+    readonly userAgent: string;
+    readonly viewport: IssueReportViewport;
+    readonly capturedAt: string;
+}) => IssueReportClientContext;

package/dist/embed/locale.d.ts

@@ -6,7 +6,7 @@ export declare const DEFAULT_LOCALE: Locale;
  *  picker (rail cycle button, avatar menu, welcome card) read from here.
  *  Tied to the codec's `DOCK_LOCALES`: the `satisfies` below pins SDK ⊆
  *  codec at compile time and locale.test.ts asserts full set equality. */
-export declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt"];
+export declare const SUPPORTED_LOCALES: readonly ["en", "es", "pt", "it"];
 /** Narrow an untrusted value (attribute, storage, navigator) to a Locale. */
 export declare const parseLocale: (value: unknown) => Locale | null;
 /**

package/dist/embed/screen-capture.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Rasterize the host page for an issue report.
+ *
+ * snapdom clones the DOM into an SVG foreignObject with styles inlined, then
+ * paints it to a canvas. It is the one such library that walks SHADOW ROOTS,
+ * which is not optional here: the dock itself lives in one, so anything else
+ * (html2canvas, notably) would photograph the host app with a hole where
+ * Belong is.
+ *
+ * KNOWN LIMITS — say them here so they are not re-discovered from a confusing
+ * report:
+ *   • cross-origin images and cross-origin iframes come out blank;
+ *   • this is a re-render of the DOM, not a photograph of pixels — a canvas
+ *     element or an unusual CSS feature can differ from what the user saw;
+ *   • it costs a beat on a large page, which is why capture runs on the click
+ *     and the dialog opens after it.
+ *
+ * DEVICE PIXEL RATIO: snapdom's `toCanvas` defaults `dpr` to
+ * `window.devicePixelRatio || 1` and multiplies the OUTPUT canvas dimensions
+ * by it, on top of `scale`. `captureScale`/`MAX_SCREENSHOT_WIDTH_PX` below
+ * only account for `scale` — so left at its default, a capture on a 2x
+ * display would produce a canvas 2x wider than the documented 1600px cap
+ * promises, inflating bytes and pushing more captures into the
+ * `MAX_SCREENSHOT_BYTES` refusal. `dpr: 1` is passed explicitly so the
+ * output is in CSS pixels and `MAX_SCREENSHOT_WIDTH_PX` means what it says
+ * regardless of the display's pixel ratio.
+ *
+ * WEBP-WITH-PNG-FALLBACK: `defaultEncode` always *requests* "image/webp". The
+ * PNG fallback is not a second encode call in this file — it is the browser's
+ * own behavior. Per the HTML spec, `HTMLCanvasElement.toBlob` given a type it
+ * cannot encode must produce `image/png` instead. So on a UA without a WebP
+ * encoder, the very same call already yields a PNG blob, and `blob.type`
+ * carries the truth of which one it got. A later task propagates `blob.type`
+ * into the upload, and the route accepts both `image/webp` and `image/png` —
+ * that is exactly why it accepts two. One consequence: PNG ignores the
+ * `quality` argument entirely, so the low-quality retry below can be a no-op
+ * on those browsers (same bytes both times) — the designed outcome there is
+ * still a report with no picture rather than an oversized upload, never a
+ * silently-too-big send.
+ *
+ * Never throws: every failure is `null`, and the dialog then offers to send the
+ * report without a picture. A capture failure must not cost us the report.
+ *
+ * A THROWN failure (as opposed to the "over the cap even at low quality"
+ * refusal above, which is not a failure) is also recorded into the client-
+ * error ring buffer (`client-error-log.ts`), so the answer to "why is there
+ * no image" travels INSIDE the report itself — the one place an operator is
+ * already looking — rather than being indistinguishable from a user who
+ * removed the screenshot or an object-store put that failed server-side.
+ * Recording is wrapped in its own try/catch: it must not be able to violate
+ * the never-throws contract above, even if the recorder itself somehow threw.
+ *
+ * The library is imported lazily so it stays out of the dock's main chunk —
+ * most sessions never open this dialog.
+ */
+export declare const MAX_SCREENSHOT_WIDTH_PX = 1600;
+export declare const MAX_SCREENSHOT_BYTES = 2000000;
+export type CapturedScreenshot = {
+    readonly blob: Blob;
+    readonly widthPx: number;
+    readonly heightPx: number;
+};
+export type Rasterizer = (element: Element, options: {
+    readonly scale: number;
+    readonly dpr: number;
+}) => Promise<HTMLCanvasElement>;
+export type Encoder = (canvas: HTMLCanvasElement, quality: number) => Promise<Blob | null>;
+/** Shrink only what is wider than the cap; never upscale. */
+export declare const captureScale: (elementWidthPx: number) => number;
+export declare const captureScreen: (input: {
+    readonly element: Element;
+    readonly rasterize?: Rasterizer;
+    readonly encode?: Encoder;
+}) => Promise<CapturedScreenshot | null>;