@proveanything/smartlinks 2.0.47 → 2.0.48

package/dist/api/comms.d.ts

@@ -1,6 +1,12 @@
 import type { CommunicationEvent, CommsQueryByUser, CommsRecipientIdsQuery, CommsRecipientsWithoutActionQuery, CommsRecipientsWithActionQuery, RecipientId, RecipientWithOutcome, LogCommunicationEventBody, LogBulkCommunicationEventsBody, AppendResult, AppendBulkResult, TransactionalSendRequest, TransactionalSendResult } from "../types/comms.js";
 /**
- * Communications namespace for sending notifications and managing user communications
+ * Communications namespace for sending notifications and managing user communications.
+ *
+ * The public preference / consent / subscription / method endpoints act only for the SIGNED-IN contact
+ * (their own contact in the collection), or for any contact when the caller is a collection admin —
+ * signed out they answer 401, someone else's contactId 403. `contactId` may be omitted to mean "me".
+ * `unsubscribe` also works signed out with a valid signed unsubscribe `token`. An email/phone
+ * registered here is only marked verified when it's the one the user signed in with.
  */
 export declare namespace comms {
     /**
@@ -37,6 +43,15 @@ export declare namespace comms {
      * GET /public/collection/:collectionId/comm/unsubscribe
      */
     function unsubscribe(collectionId: string, query: import("../types/comms.js").UnsubscribeQuery): Promise<import("../types/comms.js").UnsubscribeResponse>;
+    /**
+     * Public: sign an email address up for topics (a newsletter, updates) — works signed out.
+     * Double opt-in: nothing is consented until the address's owner clicks the confirmation link
+     * SmartLinks emails them. Always answers `{ ok: true, pending: true }` (it never reveals whether
+     * the address is already known). Topics must be ones configured in the collection's comm settings.
+     * Set comm settings `signup.confirmedUrl` to send people to your own page after confirming.
+     * POST /public/collection/:collectionId/comm/signup
+     */
+    function signup(collectionId: string, body: import("../types/comms.js").CommsSignupRequest): Promise<import("../types/comms.js").CommsSignupResponse>;
     /**
      * Public: Upsert default consent for a contact.
      * POST /public/collection/:collectionId/comm/consent

package/dist/api/comms.js

@@ -2,7 +2,13 @@
 // Communications and notifications API for Smartlinks
 import { post, request, patch } from "../http.js";
 /**
- * Communications namespace for sending notifications and managing user communications
+ * Communications namespace for sending notifications and managing user communications.
+ *
+ * The public preference / consent / subscription / method endpoints act only for the SIGNED-IN contact
+ * (their own contact in the collection), or for any contact when the caller is a collection admin —
+ * signed out they answer 401, someone else's contactId 403. `contactId` may be omitted to mean "me".
+ * `unsubscribe` also works signed out with a valid signed unsubscribe `token`. An email/phone
+ * registered here is only marked verified when it's the one the user signed in with.
  */
 export var comms;
 (function (comms) {
@@ -64,7 +70,8 @@ export var comms;
      */
     async function unsubscribe(collectionId, query) {
         const params = new URLSearchParams();
-        params.set('contactId', query.contactId);
+        if (query.contactId)
+            params.set('contactId', query.contactId);
         if (query.topic)
             params.set('topic', query.topic);
         if (query.channel)
@@ -76,6 +83,19 @@ export var comms;
         return request(path);
     }
     comms.unsubscribe = unsubscribe;
+    /**
+     * Public: sign an email address up for topics (a newsletter, updates) — works signed out.
+     * Double opt-in: nothing is consented until the address's owner clicks the confirmation link
+     * SmartLinks emails them. Always answers `{ ok: true, pending: true }` (it never reveals whether
+     * the address is already known). Topics must be ones configured in the collection's comm settings.
+     * Set comm settings `signup.confirmedUrl` to send people to your own page after confirming.
+     * POST /public/collection/:collectionId/comm/signup
+     */
+    async function signup(collectionId, body) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/comm/signup`;
+        return post(path, body);
+    }
+    comms.signup = signup;
     /**
      * Public: Upsert default consent for a contact.
      * POST /public/collection/:collectionId/comm/consent
@@ -109,7 +129,8 @@ export var comms;
      */
     async function checkSubscription(collectionId, query) {
         const params = new URLSearchParams();
-        params.set('contactId', query.contactId);
+        if (query.contactId)
+            params.set('contactId', query.contactId);
         params.set('subjectType', query.subjectType);
         params.set('subjectId', query.subjectId);
         if (query.productId)
@@ -125,7 +146,8 @@ export var comms;
      */
     async function listMethods(collectionId, query) {
         const params = new URLSearchParams();
-        params.set('contactId', query.contactId);
+        if (query.contactId)
+            params.set('contactId', query.contactId);
         if (query.type)
             params.set('type', query.type);
         const qs = `?${params.toString()}`;

package/dist/api/functions.js

@@ -27,7 +27,9 @@
 // installed release regardless.
 import { post, request, getAppContext, getAppChannel } from "../http.js";
 import { readContext } from "../context.js";
-const CHANNELS = ['dev', 'alpha', 'beta', 'stable'];
+// 'preview' = the app's in-progress server code inside Forge's preview (needs the preview pass Forge
+// puts in the context as `slPreview`; SmartLinks refuses preview calls without it).
+const CHANNELS = ['dev', 'alpha', 'beta', 'stable', 'preview'];
 /**
  * The release channel a call targets, or undefined for "the collection's installed release".
  * A host context `appChannel` can be scoped to ONE app with `appChannelApp` — needed where several
@@ -52,6 +54,16 @@ export function resolveFunctionChannel(opts = {}, appId) {
         throw new Error(`Unknown release channel "${raw}" (expected ${CHANNELS.join(' | ')})`);
     return ch;
 }
+/** Add Forge's preview pass to a preview-channel URL (a query param, so host API proxies keep it). */
+function withPreviewPass(url, ch, appId) {
+    if (ch !== 'preview')
+        return url;
+    const ctx = readContext();
+    if (ctx.appChannelApp && appId && ctx.appChannelApp !== appId)
+        return url;
+    const pass = ctx.slPreview;
+    return pass ? `${url}${url.includes('?') ? '&' : '?'}slPreview=${encodeURIComponent(pass)}` : url;
+}
 function appBase(surface, collectionId, opts) {
     var _a;
     const c = encodeURIComponent(collectionId);
@@ -63,7 +75,10 @@ function appBase(surface, collectionId, opts) {
 }
 /** The API path a function call goes to (exported for hosts/tests that need the exact URL). */
 export function functionPath(surface, collectionId, name, opts = {}) {
-    return `${appBase(surface, collectionId, opts)}/functions/${encodeURIComponent(name)}`;
+    var _a;
+    const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+    const ch = app ? resolveFunctionChannel(opts, app) : undefined;
+    return withPreviewPass(`${appBase(surface, collectionId, opts)}/functions/${encodeURIComponent(name)}`, ch, app);
 }
 const fnPath = functionPath;
 export var functions;
@@ -123,7 +138,10 @@ export var functions;
      * appId is given (or set as the SDK app context): `GET /public/collection/:c[/app/:appId]/functions`.
      */
     async function list(collectionId, opts = {}) {
-        return request(`${appBase('public', collectionId, opts)}/functions`);
+        var _a;
+        const app = (_a = opts.appId) !== null && _a !== void 0 ? _a : getAppContext();
+        const ch = app ? resolveFunctionChannel(opts, app) : undefined;
+        return request(withPreviewPass(`${appBase('public', collectionId, opts)}/functions`, ch, app));
     }
     functions.list = list;
 })(functions || (functions = {}));

package/dist/context.d.ts

@@ -10,6 +10,11 @@ export interface SmartLinksContext {
     appChannel?: string;
     /** Limits `appChannel` to one app (where several apps share a page, e.g. a portal preview). */
     appChannelApp?: string;
+    /**
+     * Forge's preview pass: lets this preview run the app's in-progress server code
+     * (`appChannel: 'preview'`) on this collection. Set by Forge; never present elsewhere.
+     */
+    slPreview?: string;
     /** Any other declared view params (e.g. pageId, voteId, orientation, tvMode). */
     [key: string]: string | undefined;
 }

package/dist/context.js

@@ -54,6 +54,7 @@ export function readContext(overrides) {
                 fill('appChannel', site.channel);
                 fill('appChannelApp', site.appId);
             }
+            fill('slPreview', site.previewPass);
         }
     }
     catch (_a) {

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.0.47  |  Generated: 2026-10-08T12:38:10.855Z
+Version: 2.0.48  |  Generated: 2026-10-09T09:58:35.560Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2401,6 +2401,17 @@ interface AppWidgetComponent {
   optional?: string[];
   };
   settings?: Record<string, any>;
+  styleSupport?: WidgetStyleSupport;
+}
+```
+
+**WidgetStyleSupport** (interface)
+```typescript
+interface WidgetStyleSupport {
+  accent?: boolean;
+  text?: boolean;
+  textAlign?: boolean;
+  background?: 'transparent' | 'own';
 }
 ```
 
@@ -5140,7 +5151,7 @@ interface PushSubscribeResponse {
 **RegisterPushMethodRequest** (interface)
 ```typescript
 interface RegisterPushMethodRequest {
-  contactId: string
+  contactId?: string
   endpoint: string
   keys: { p256dh: string; auth: string }
   meta?: Record<string, any>
@@ -5200,7 +5211,7 @@ interface CommsPublicTopicsResponse {
 **UnsubscribeQuery** (interface)
 ```typescript
 interface UnsubscribeQuery {
-  contactId: string
+  contactId?: string
   topic?: string
   channel?: BroadcastChannel
   token?: string
@@ -5214,10 +5225,26 @@ interface UnsubscribeResponse {
 }
 ```
 
+**CommsSignupRequest** (interface)
+```typescript
+interface CommsSignupRequest {
+  email: string
+  topics?: string[]
+  firstName?: string
+}
+```
+
+**CommsSignupResponse** (interface)
+```typescript
+interface CommsSignupResponse {
+  ok: true; pending: true
+}
+```
+
 **CommsConsentUpsertRequest** (interface)
 ```typescript
 interface CommsConsentUpsertRequest {
-  contactId: string
+  contactId?: string
   channels?: ConsentChannels
   topics?: Record<string, boolean>
   topicsByChannel?: Partial<Record<BroadcastChannel, Record<string, boolean>>>
@@ -5227,7 +5254,7 @@ interface CommsConsentUpsertRequest {
 **CommsPreferencesUpsertRequest** (interface)
 ```typescript
 interface CommsPreferencesUpsertRequest {
-  contactId: string
+  contactId?: string
   subject?: { type: SubjectType; id: string; productId?: string }
   channels?: ConsentChannels
   topics?: Record<string, boolean>
@@ -5238,7 +5265,7 @@ interface CommsPreferencesUpsertRequest {
 **CommsSubscribeRequest** (interface)
 ```typescript
 interface CommsSubscribeRequest {
-  contactId: string
+  contactId?: string
   subject: { type: SubjectType; id: string; productId?: string }
   subscribe: boolean
   source?: string
@@ -5255,7 +5282,7 @@ interface CommsSubscribeResponse {
 **CommsSubscriptionCheckQuery** (interface)
 ```typescript
 interface CommsSubscriptionCheckQuery {
-  contactId: string
+  contactId?: string
   subjectType: SubjectType
   subjectId: string
   productId?: string
@@ -5272,7 +5299,7 @@ interface CommsSubscriptionCheckResponse {
 **CommsListMethodsQuery** (interface)
 ```typescript
 interface CommsListMethodsQuery {
-  contactId: string
+  contactId?: string
   type?: BroadcastChannel
 }
 ```
@@ -5502,7 +5529,8 @@ export interface PushSubscribeResponse { ok: true; id: string }
 
 // Public: register a push contact method
 export interface RegisterPushMethodRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   endpoint: string
   keys: { p256dh: string; auth: string }
   meta?: Record<string, any>
@@ -5557,7 +5585,8 @@ export type CommsSettingsPatchBody = Partial<CommsSettings>
 export interface CommsPublicTopicsResponse { ok: true; topics: Record<string, TopicConfig> }
 
 export interface UnsubscribeQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   topic?: string
   channel?: BroadcastChannel
   token?: string
@@ -5565,19 +5594,30 @@ export interface UnsubscribeQuery {
 
 export interface UnsubscribeResponse { ok: true; applied?: { channels?: Record<string, boolean>; topics?: Record<string, boolean> } }
 
+// Public sign-up (double opt-in)
+export interface CommsSignupRequest {
+  email: string
+  /** Topic ids from the collection's comm settings (e.g. ["newsletter"]). */
+  topics?: string[]
+  firstName?: string
+}
+export interface CommsSignupResponse { ok: true; pending: true }
+
 // Public consent/preferences/subscribe
 export type ConsentChannels = Partial<Record<BroadcastChannel, boolean>>
 type SubjectType = import('./contact').SubjectType
 
 export interface CommsConsentUpsertRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   channels?: ConsentChannels
   topics?: Record<string, boolean>
   topicsByChannel?: Partial<Record<BroadcastChannel, Record<string, boolean>>>
 }
 
 export interface CommsPreferencesUpsertRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subject?: { type: SubjectType; id: string; productId?: string }
   channels?: ConsentChannels
   topics?: Record<string, boolean>
@@ -5585,7 +5625,8 @@ export interface CommsPreferencesUpsertRequest {
 }
 
 export interface CommsSubscribeRequest {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subject: { type: SubjectType; id: string; productId?: string }
   subscribe: boolean
   source?: string
@@ -5593,7 +5634,8 @@ export interface CommsSubscribeRequest {
 export interface CommsSubscribeResponse { ok: true; subscriptionId: string }
 
 export interface CommsSubscriptionCheckQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   subjectType: SubjectType
   subjectId: string
   productId?: string
@@ -5601,7 +5643,8 @@ export interface CommsSubscriptionCheckQuery {
 export interface CommsSubscriptionCheckResponse { ok: true; subscribed: boolean }
 
 export interface CommsListMethodsQuery {
-  contactId: string
+  /** Optional: defaults to the signed-in user's own contact. Only collection admins may name another contact. */
+  contactId?: string
   type?: BroadcastChannel
 }
 export interface CommsListMethodsResponse { ok: true; methods: import('./contact').CommMethod[] }
@@ -10921,82 +10964,86 @@ Invite a user to a collection by email (admin only). Creates or links their acco
 **getPushVapidPublicKey**(collectionId: string) → `Promise<import("../types/comms").PushVapidResponse>`
 Public: Get VAPID public key used for Web Push subscriptions. GET /public/collection/:collectionId/comm/push/vapidPublicKey Note: Key may be global; path is collection-scoped for consistency.
 
-**registerPush**(collectionId: string,
+**registerPush**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register a Web Push subscription under unified comms. POST /public/collection/:collectionId/comm/push/register
 
-**getSettings**(collectionId: string,
+**getSettings**(collectionId: string,
     opts: { includeSecret?: boolean } = {}) → `Promise<import("../types/comms").CommsSettingsGetResponse>`
 Admin: Get current comms settings for a collection. GET /admin/collection/:collectionId/comm.settings Optional query: includeSecret=true to include unsub.secret in response.
 
-**patchSettings**(collectionId: string,
+**patchSettings**(collectionId: string,
     body: import("../types/comms") → `void`
 Admin: Patch comms settings for a collection. PATCH /admin/collection/:collectionId/comm.settings
 
 **getPublicTopics**(collectionId: string) → `Promise<import("../types/comms").CommsPublicTopicsResponse>`
 Public: Fetch configured topics for a collection. GET /public/collection/:collectionId/comm/topics
 
-**unsubscribe**(collectionId: string,
+**unsubscribe**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Unsubscribe a contact from a category or channel. GET /public/collection/:collectionId/comm/unsubscribe
 
-**upsertConsent**(collectionId: string,
+**signup**(collectionId: string,
+    body: import("../types/comms") → `void`
+Public: sign an email address up for topics (a newsletter, updates) — works signed out. Double opt-in: nothing is consented until the address's owner clicks the confirmation link SmartLinks emails them. Always answers `{ ok: true, pending: true }` (it never reveals whether the address is already known). Topics must be ones configured in the collection's comm settings. Set comm settings `signup.confirmedUrl` to send people to your own page after confirming. POST /public/collection/:collectionId/comm/signup
+
+**upsertConsent**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert default consent for a contact. POST /public/collection/:collectionId/comm/consent
 
-**upsertPreferences**(collectionId: string,
+**upsertPreferences**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Upsert preferences for a specific subject (or default if subject omitted). POST /public/collection/:collectionId/comm/preferences
 
-**subscribe**(collectionId: string,
+**subscribe**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Subscribe/unsubscribe contact to a subject. POST /public/collection/:collectionId/comm/subscribe
 
-**checkSubscription**(collectionId: string,
+**checkSubscription**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: Check subscription status for a subject. GET /public/collection/:collectionId/comm/subscription/check
 
-**listMethods**(collectionId: string,
+**listMethods**(collectionId: string,
     query: import("../types/comms") → `void`
 Public: List registered contact methods. GET /public/collection/:collectionId/comm/methods
 
-**registerEmail**(collectionId: string,
+**registerEmail**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register email method for a contact. POST /public/collection/:collectionId/comm/email/register
 
-**registerSms**(collectionId: string,
+**registerSms**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Register SMS method for a contact. POST /public/collection/:collectionId/comm/sms/register
 
-**resolveSubscriptions**(collectionId: string,
+**resolveSubscriptions**(collectionId: string,
     body: import("../types/comms") → `void`
 Public: Resolve contacts for a subject with identity hints. POST /public/collection/:collectionId/comm/subscriptions/resolve
 
-**queryByUser**(collectionId: string,
+**queryByUser**(collectionId: string,
     body: CommsQueryByUser = {}) → `Promise<CommunicationEvent[]>`
 Analytics: Query communication events by user or contact. POST /admin/collection/:collectionId/comm/query/by-user
 
-**queryRecipientIds**(collectionId: string,
+**queryRecipientIds**(collectionId: string,
     body: CommsRecipientIdsQuery) → `Promise<RecipientId[]>`
 Analytics: Recipient IDs for a communication source. POST /admin/collection/:collectionId/comm/query/recipient-ids
 
-**queryRecipientsWithoutAction**(collectionId: string,
+**queryRecipientsWithoutAction**(collectionId: string,
     body: CommsRecipientsWithoutActionQuery) → `Promise<RecipientId[]>`
 Analytics: Recipients who did not perform an action. POST /admin/collection/:collectionId/comm/query/recipients/without-action
 
-**queryRecipientsWithAction**(collectionId: string,
+**queryRecipientsWithAction**(collectionId: string,
     body: CommsRecipientsWithActionQuery) → `Promise<RecipientId[] | RecipientWithOutcome[]>`
 Analytics: Recipients who performed an action, optionally with outcome. POST /admin/collection/:collectionId/comm/query/recipients/with-action
 
-**sendTransactional**(collectionId: string,
+**sendTransactional**(collectionId: string,
     body: TransactionalSendRequest) → `Promise<TransactionalSendResult>`
 Send a single transactional message to one contact using a template. No broadcast record is created. The send is logged to the contact's communication history with sourceType: 'transactional'. POST /admin/collection/:collectionId/comm/send ```typescript const result = await comms.sendTransactional(collectionId, { contactId:  'e4f2a1b0-...', templateId: 'warranty-update', channel:    'preferred', props:      { claimRef: 'CLM-0042', decision: 'approved' }, include:    { productId: 'prod-abc123', appCase: 'c9d1e2f3-...' }, ref:        'warranty-decision-notification', appId:      'warrantyApp', }) if (result.ok) { console.log(`Sent via ${result.channel}`, result.messageId) } else { console.error('Send failed:', result.error) } ```
 
-**logCommunicationEvent**(collectionId: string,
+**logCommunicationEvent**(collectionId: string,
     body: LogCommunicationEventBody) → `Promise<AppendResult>`
 Logging: Append a single communication event. POST /admin/collection/:collectionId/comm/log
 
-**logBulkCommunicationEvents**(collectionId: string,
+**logBulkCommunicationEvents**(collectionId: string,
     body: LogBulkCommunicationEventsBody | ({ sourceId: string; ids: string[]; idField?: 'userId'|'contactId'; [k: string]: any }) → `void`
 Logging: Append many communication events for a list of IDs. POST /admin/collection/:collectionId/comm/log/bulk
 

package/dist/docs/comms.md

@@ -313,9 +313,30 @@ function effectivePolicy(topic: any, channel: 'email' | 'sms' | 'push' | 'wallet
 }
 ```
 
+### Sign-up with double opt-in (newsletters)
+
+For a sign-up form — works signed out. SmartLinks emails the address a "confirm your subscription"
+link; nothing is consented until it's clicked. The answer is always the same, so the form can't be
+used to find out who's registered.
+
+```typescript
+await comms.signup('collectionId', { email: 'sam@example.com', topics: ['newsletter'] })
+// → { ok: true, pending: true }  — tell the visitor to check their inbox
+```
+
+- Topics must exist in the collection's comm settings. Give a newsletter topic
+  `defaults.policy: 'opt-in'`: broadcasts on an opt-in topic only reach people who said yes
+  (confirmed sign-ups), never the whole contact list.
+- Confirming turns on the email channel and the topics, and marks the address verified.
+- Set comm settings `signup.confirmedUrl` (https) to send people to your own "thanks" page after
+  they confirm (`?confirmed=1`, or `0` for an expired link); otherwise SmartLinks shows a short page.
+
 ### Consent (Default)
 
-Record a contact's default channel and topic opt-ins.
+Record a contact's default channel and topic opt-ins. These calls (consent, preferences, subscribe,
+methods, push/email/SMS registration) act for the **signed-in** contact — `contactId` may be omitted
+to mean "me"; only collection admins may name another contact. An email registered here is verified
+only if it's the one the user signed in with; any other address is sent a confirmation link.
 
 ```typescript
 await comms.upsertConsent('collectionId', {

package/dist/docs/deploying-apps.md

@@ -165,6 +165,17 @@ The canonical channels are **`dev` · `alpha` · `beta` · `stable`**. Legacy `p
 A collection chooses which channel it follows, so you can point a test collection at `dev`
 and exercise a build before it reaches `prod`.
 
+### `preview` — server code while you build (Forge)
+
+Forge publishes an app's **server functions only** to a private `preview` channel whenever the
+agent changes them, so the app's own preview can call the new code straight away. It is not a
+channel a collection can follow, release to or promote from. A preview call runs only with the
+**preview pass** Forge gives its preview — for one app on one collection, for a few hours — so
+nobody else ever runs in-progress server code, while the builder can preview against any
+collection they administer. The SDK sends the pass automatically (`SL.functions` with
+`appChannel: 'preview'` and `slPreview` in the context); apps need no code for it. `dev` only
+changes when you choose to release to it.
+
 ---
 
 ## Deploy keys

package/dist/docs/widgets.md

@@ -651,6 +651,78 @@ Widgets use semantic class names that reference these variables:
 <Button className="bg-blue-500 text-white">
 ```
 
+### Style support — how a widget takes styling from where it's placed
+
+Hosts that place widgets (Link Page, Hub, …) offer per-widget styling: width, alignment, padding,
+scale, corners, border, background, and colours. The host only ever styles the **box** around the
+widget; it never reaches inside (no selector tricks, no `!important`). So a widget **declares** what
+it honours, the host shows only those controls, and colours reach the widget through variables.
+
+**Declare it** on the widget's entry in `app.manifest.json` (`widgets.components[]`):
+
+```jsonc
+{
+  "name": "TapToDonate",
+  "styleSupport": {
+    "accent": true,          // reads --sl-widget-accent / --sl-widget-accent-contrast
+    "text": true,            // reads --sl-widget-text
+    "textAlign": true,       // titles/messages use text-align: inherit
+    "background": "transparent"  // or "own" if it paints its own card
+  }
+}
+```
+
+List only what you actually implemented. No `styleSupport` (older widgets) → the host offers layout
+controls only and says the widget has no colour customisation; nothing breaks.
+
+| Setting | Owner | Works when |
+|---|---|---|
+| width, alignment, padding, scale | Host | always (scale: keep 60–130%) |
+| radius, border | Host | always — visible when the widget is transparent or fills its box |
+| background | Host | the widget is transparent (hidden when `background: "own"`) |
+| text | Widget | declared, and the widget reads `--sl-widget-text` |
+| accent | Widget | declared, and the widget reads `--sl-widget-accent` + `--sl-widget-accent-contrast` |
+| textAlign | Widget | declared, and the widget uses `text-align: inherit` |
+| anything else (shapes, button style…) | Widget | the widget's own `settings` schema — not host styling |
+
+**Variables the host sets** on the box (only the ones chosen):
+
+```css
+--sl-widget-accent            /* hex */
+--sl-widget-accent-contrast   /* readable text on the accent: #111111 or #ffffff */
+--sl-widget-text              /* hex */
+--sl-widget-radius            /* e.g. 12px — use it on your own rounded elements */
+```
+
+**Widget rules**
+
+1. **Transparent by default** — the root element has no background, border or padding of its own.
+   Need a card look? Declare `background: "own"` and make the card one of the widget's own settings.
+2. **Read the variables with fallbacks** to the theme tokens, for every colour that should follow:
+   `background: var(--sl-widget-accent, var(--sl-color-accent));`
+   `color: var(--sl-widget-accent-contrast, var(--sl-color-on-accent));`
+   `color: var(--sl-widget-text, inherit);`
+3. **Inherit text** — `color: inherit` / `text-align: inherit` on headings and messages if you declare
+   `text` / `textAlign`.
+4. **No hardcoded colours** for buttons, links or focus rings — accent + accent-contrast.
+5. **No global CSS** — ship scoped styles; nothing may affect elements outside the widget's box.
+
+**Hosts** use the SDK helpers so every host behaves the same:
+
+```ts
+import { widgetStyleControls, widgetStyleVars } from '@proveanything/smartlinks'
+
+const controls = widgetStyleControls(component.styleSupport)   // which controls to show
+const vars = widgetStyleVars({ accent, text, radius }, component.styleSupport) // CSS vars for the box
+```
+
+Conformance checklist (per widget, in the host's editor preview and live): unstyled looks as before
+(light and dark); Background fills the whole box (unless `own`); Text recolours all text; Accent
+recolours every button, link, focus ring and active state, and labels stay readable (try yellow and
+near-black); undeclared controls are absent; padding 0 and 40 don't clip or double up; radius 0 and
+32 with a border clip cleanly; width 50% at each alignment; scale 60% and 130% don't overlap
+neighbours; dialogs opened from the widget are unaffected; nothing outside the box changes.
+
 ---
 
 ## Best Practices

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export * from "./api/index.js";
 export * from "./types/index.js";
 export { iframe } from "./iframe.js";
 export { readContext } from "./context.js";
+export { widgetStyleVars, widgetStyleControls, readableOn, WIDGET_STYLE_VARS } from "./widgetStyle.js";
+export type { WidgetStyling } from "./widgetStyle.js";
 export type { SmartLinksContext } from "./context.js";
 export type { InvalidateCacheOptions } from "./http.js";
 export * as cache from './cache.js';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./types/index.js";
 export { iframe } from "./iframe.js";
 // App context reader (props → hash → search), for pages and containers alike
 export { readContext } from "./context.js";
+export { widgetStyleVars, widgetStyleControls, readableOn, WIDGET_STYLE_VARS } from "./widgetStyle.js";
 import * as cache_1 from './cache.js';
 export { cache_1 as cache };
 // IframeResponder (also exported via iframe namespace)