From c32fbd47385be026fd6c6d5ff82ee174a4132c3a Mon Sep 17 00:00:00 2001 From: Mathieu2301 <21021423+Mathieu2301@users.noreply.github.com> Date: Wed, 18 Nov 2026 05:36:23 +0100 Subject: [PATCH] feat(app): home.share() and home.copy() through the shell (CLI 4.6.0) A house frame cannot open the share sheet or write the clipboard. The SDK exposes share/copy, which ask Miakapp synchronously from the tap handler and resolve shared / copied / cancelled / unavailable; older shells answer unavailable. The agent guide and the members guide say how to use it for an invite link. --- docs/agent-guide.md | 7 +++++ packages/app/src/index.ts | 29 +++++++++++++++++++ packages/app/test/app.test.ts | 25 ++++++++++++++++ packages/cli/assets/agent-guide.md | 7 +++++ packages/cli/assets/members.md | 4 +++ .../cli/assets/starter/app/app/miakapp.ts | 29 +++++++++++++++++++ packages/cli/package.json | 2 +- packages/cli/src/version.ts | 2 +- 8 files changed, 103 insertions(+), 2 deletions(-) diff --git a/docs/agent-guide.md b/docs/agent-guide.md index 05c0b4e..554e0bc 100644 --- a/docs/agent-guide.md +++ b/docs/agent-guide.md @@ -398,6 +398,13 @@ redraw, but `home.bar.setButtons()` can add one or two of your own screens to it people, bell), each with an optional `badge` count (e.g. join requests waiting; 0 shows none). Call it again whenever the count changes. +Your frame cannot open the share sheet or write the clipboard. For a "Share" or +"Copy" button, call `home.share({ title, text, url })` or `home.copy(text)` +directly in the tap handler: Miakapp does it (share sheet, else copy), only on +that fresh tap, url https only. It resolves `'shared'`, `'copied'`, +`'cancelled'` or `'unavailable'`; tell the resident which, and on +`'unavailable'` show the text in a read-only field. + Declare every state path (exact or `prefix.*`) under `app.requires.state_read` and every function under `app.requires.call`. Events, media and `miakapp.*` functions are refused by `miakapp check`. Show `state.stale`, disable controls diff --git a/packages/app/src/index.ts b/packages/app/src/index.ts index d93772d..da23da2 100644 --- a/packages/app/src/index.ts +++ b/packages/app/src/index.ts @@ -52,6 +52,16 @@ export interface BarButton { readonly badge?: number; } +/** How a share or copy ended; on 'unavailable', show the link so it can be copied by hand. */ +export type ShareResult = 'shared' | 'copied' | 'cancelled' | 'unavailable'; + +/** What `home.share()` hands to the share sheet; the url must be https. */ +export interface ShareData { + readonly title?: string; + readonly text?: string; + readonly url?: string; +} + export interface HomeState { readonly values: Readonly>; readonly revision: number; @@ -79,6 +89,9 @@ export interface MiakappHost { readonly can: { read(path: string): boolean; call(name: string): boolean }; call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise; ready(): void; + /** Absent on shells older than 2026-11-18 (share and copy). */ + share?(data: ShareData): Promise; + copy?(text: string): Promise<'copied' | 'unavailable'>; /** Absent on shells older than the bottom bar. */ readonly bar?: { setButtons(buttons: readonly BarButton[]): void; @@ -131,6 +144,16 @@ export interface Home { call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise; /** Lifts the shell's loading screen before the script finishes, if you want. */ ready(): void; + /** + * Opens the share sheet (or copies the link when there is none). Your frame + * cannot do it itself: Miakapp does, so call it straight from a tap handler + * (no await before it). Limits: title 200, text 2000, url 2048 and https only. + * Resolves 'unavailable' without a fresh tap or on an older Miakapp: then + * show the link in a field so it can be copied by hand. + */ + share(data: ShareData): Promise; + /** Copies text (≤ 4096) to the clipboard; same rules as `share`. */ + copy(text: string): Promise<'copied' | 'unavailable'>; /** * The home's own buttons in the Miakapp bar, between the home tab and « Me ». * Miakapp keeps the last list for the next visit; set it on every start. @@ -196,6 +219,12 @@ export function connect(scope: { readonly miakapp?: unknown } = globalThis as { await host.call(name, args ?? null, options ?? {}) as T ), ready: () => host.ready(), + share: async (data: ShareData) => ( + typeof host.share === 'function' ? await host.share(data) : 'unavailable' as const + ), + copy: async (text: string) => ( + typeof host.copy === 'function' ? await host.copy(text) : 'unavailable' as const + ), bar: Object.freeze({ setButtons: (buttons: readonly BarButton[]) => host.bar?.setButtons(buttons), onSelect: (listener: (id: string | null) => void) => host.bar?.onSelect(listener) ?? (() => undefined), diff --git a/packages/app/test/app.test.ts b/packages/app/test/app.test.ts index 3af8d05..cb403a4 100644 --- a/packages/app/test/app.test.ts +++ b/packages/app/test/app.test.ts @@ -132,3 +132,28 @@ describe('the Miakapp bar', () => { expect(typeof home.bar.onSelect(() => undefined)).toBe('function'); }); }); + +describe('share and copy', () => { + test('asks the shell, synchronously, and returns its answer', async () => { + const { host } = fakeHost({}); + const asked: unknown[] = []; + const home = connect({ + miakapp: { + ...host, + share: (data: unknown) => { asked.push(data); return Promise.resolve('shared' as const); }, + copy: (text: string) => { asked.push(text); return Promise.resolve('copied' as const); }, + }, + }); + const shared = home.share({ title: 'Maison', url: 'https://www.miakapp.com/h/a?invite=x' }); + // Called before any await, while the resident's tap is still fresh. + expect(asked).toEqual([{ title: 'Maison', url: 'https://www.miakapp.com/h/a?invite=x' }]); + expect(await shared).toBe('shared'); + expect(await home.copy('abc')).toBe('copied'); + }); + + test('answers unavailable on an older shell', async () => { + const home = connect({ miakapp: fakeHost({}).host }); + expect(await home.share({ url: 'https://example.com' })).toBe('unavailable'); + expect(await home.copy('abc')).toBe('unavailable'); + }); +}); diff --git a/packages/cli/assets/agent-guide.md b/packages/cli/assets/agent-guide.md index 05c0b4e..554e0bc 100644 --- a/packages/cli/assets/agent-guide.md +++ b/packages/cli/assets/agent-guide.md @@ -398,6 +398,13 @@ redraw, but `home.bar.setButtons()` can add one or two of your own screens to it people, bell), each with an optional `badge` count (e.g. join requests waiting; 0 shows none). Call it again whenever the count changes. +Your frame cannot open the share sheet or write the clipboard. For a "Share" or +"Copy" button, call `home.share({ title, text, url })` or `home.copy(text)` +directly in the tap handler: Miakapp does it (share sheet, else copy), only on +that fresh tap, url https only. It resolves `'shared'`, `'copied'`, +`'cancelled'` or `'unavailable'`; tell the resident which, and on +`'unavailable'` show the text in a read-only field. + Declare every state path (exact or `prefix.*`) under `app.requires.state_read` and every function under `app.requires.call`. Events, media and `miakapp.*` functions are refused by `miakapp check`. Show `state.stale`, disable controls diff --git a/packages/cli/assets/members.md b/packages/cli/assets/members.md index 7c6cb6b..da95b9f 100644 --- a/packages/cli/assets/members.md +++ b/packages/cli/assets/members.md @@ -70,6 +70,10 @@ interface Member { `{ role, exp, nonce }`; the coordinator keeps the secret and a revocation list, checks signature, expiry and revocation, and admits once per account (optionally single use). + To hand the link over, call `home.share({ title, url })` straight from the + Invite/Share button's tap handler (the frame cannot reach the share sheet or + the clipboard; Miakapp does it, with a copy fallback). On `'unavailable'`, + show the link in a read-only field so it can be copied by hand. The app reads `home.link.params.invite` on start and, if present, calls `members.redeem({ code })`. Never trust the app: the coordinator checks everything. diff --git a/packages/cli/assets/starter/app/app/miakapp.ts b/packages/cli/assets/starter/app/app/miakapp.ts index d93772d..da23da2 100644 --- a/packages/cli/assets/starter/app/app/miakapp.ts +++ b/packages/cli/assets/starter/app/app/miakapp.ts @@ -52,6 +52,16 @@ export interface BarButton { readonly badge?: number; } +/** How a share or copy ended; on 'unavailable', show the link so it can be copied by hand. */ +export type ShareResult = 'shared' | 'copied' | 'cancelled' | 'unavailable'; + +/** What `home.share()` hands to the share sheet; the url must be https. */ +export interface ShareData { + readonly title?: string; + readonly text?: string; + readonly url?: string; +} + export interface HomeState { readonly values: Readonly>; readonly revision: number; @@ -79,6 +89,9 @@ export interface MiakappHost { readonly can: { read(path: string): boolean; call(name: string): boolean }; call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise; ready(): void; + /** Absent on shells older than 2026-11-18 (share and copy). */ + share?(data: ShareData): Promise; + copy?(text: string): Promise<'copied' | 'unavailable'>; /** Absent on shells older than the bottom bar. */ readonly bar?: { setButtons(buttons: readonly BarButton[]): void; @@ -131,6 +144,16 @@ export interface Home { call(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise; /** Lifts the shell's loading screen before the script finishes, if you want. */ ready(): void; + /** + * Opens the share sheet (or copies the link when there is none). Your frame + * cannot do it itself: Miakapp does, so call it straight from a tap handler + * (no await before it). Limits: title 200, text 2000, url 2048 and https only. + * Resolves 'unavailable' without a fresh tap or on an older Miakapp: then + * show the link in a field so it can be copied by hand. + */ + share(data: ShareData): Promise; + /** Copies text (≤ 4096) to the clipboard; same rules as `share`. */ + copy(text: string): Promise<'copied' | 'unavailable'>; /** * The home's own buttons in the Miakapp bar, between the home tab and « Me ». * Miakapp keeps the last list for the next visit; set it on every start. @@ -196,6 +219,12 @@ export function connect(scope: { readonly miakapp?: unknown } = globalThis as { await host.call(name, args ?? null, options ?? {}) as T ), ready: () => host.ready(), + share: async (data: ShareData) => ( + typeof host.share === 'function' ? await host.share(data) : 'unavailable' as const + ), + copy: async (text: string) => ( + typeof host.copy === 'function' ? await host.copy(text) : 'unavailable' as const + ), bar: Object.freeze({ setButtons: (buttons: readonly BarButton[]) => host.bar?.setButtons(buttons), onSelect: (listener: (id: string | null) => void) => host.bar?.onSelect(listener) ?? (() => undefined), diff --git a/packages/cli/package.json b/packages/cli/package.json index 2bc7149..feec23a 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@miakapp/cli", - "version": "4.5.2", + "version": "4.6.0", "description": "Agent-first Miakapp command line: check, build, publish, activate and roll back home interfaces", "type": "module", "engines": { diff --git a/packages/cli/src/version.ts b/packages/cli/src/version.ts index f5ee445..4963038 100644 --- a/packages/cli/src/version.ts +++ b/packages/cli/src/version.ts @@ -12,4 +12,4 @@ */ export const PACKAGE_NAME = '@miakapp/cli'; -export const CLI_VERSION = '4.5.2'; +export const CLI_VERSION = '4.6.0';