Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/agent-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 29 additions & 0 deletions packages/app/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Record<string, unknown>>;
readonly revision: number;
Expand Down Expand Up @@ -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<unknown>;
ready(): void;
/** Absent on shells older than 2026-11-18 (share and copy). */
share?(data: ShareData): Promise<ShareResult>;
copy?(text: string): Promise<'copied' | 'unavailable'>;
/** Absent on shells older than the bottom bar. */
readonly bar?: {
setButtons(buttons: readonly BarButton[]): void;
Expand Down Expand Up @@ -131,6 +144,16 @@ export interface Home {
call<T = unknown>(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<T>;
/** 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<ShareResult>;
/** 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.
Expand Down Expand Up @@ -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),
Expand Down
25 changes: 25 additions & 0 deletions packages/app/test/app.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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');
});
});
7 changes: 7 additions & 0 deletions packages/cli/assets/agent-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions packages/cli/assets/members.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
29 changes: 29 additions & 0 deletions packages/cli/assets/starter/app/app/miakapp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<Record<string, unknown>>;
readonly revision: number;
Expand Down Expand Up @@ -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<unknown>;
ready(): void;
/** Absent on shells older than 2026-11-18 (share and copy). */
share?(data: ShareData): Promise<ShareResult>;
copy?(text: string): Promise<'copied' | 'unavailable'>;
/** Absent on shells older than the bottom bar. */
readonly bar?: {
setButtons(buttons: readonly BarButton[]): void;
Expand Down Expand Up @@ -131,6 +144,16 @@ export interface Home {
call<T = unknown>(name: string, args?: unknown, options?: { timeoutMs?: number }): Promise<T>;
/** 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<ShareResult>;
/** 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.
Expand Down Expand Up @@ -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),
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/package.json
Original file line number Diff line number Diff line change
@@ -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": {
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/version.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@
*/
export const PACKAGE_NAME = '@miakapp/cli';

export const CLI_VERSION = '4.5.2';
export const CLI_VERSION = '4.6.0';
Loading