@await-widget/runtime 0.0.48 → 0.0.50

package/bin/await-widget.js

@@ -25,7 +25,6 @@ const crcTable = makeCrcTable();
 const bridgeInfoDirectory = '.await';
 const bridgeInfoFileName = 'bridge.json';
 const singleWidgetPath = '.';
-const widgetDirectoryError = 'Run await-widget from a package root or first-level widget folder whose package.json includes @await-widget/runtime.';
 
 function main() {
 	const options = parseArgs(process.argv.slice(2));
@@ -139,16 +138,15 @@ function parseAppArgs(args) {
 }
 
 async function startWorkspaceServer(options) {
-	let roots;
+	const workspaceRoot = process.cwd();
+	let widgetRoot;
 	try {
-		roots = await resolveWidgetServerRoots(process.cwd());
+		widgetRoot = await selectWidgetRoot(workspaceRoot);
 	} catch (error) {
 		console.error(error.message);
 		process.exit(1);
 	}
 
-	const {packageRoot, widgetRoot} = roots;
-
 	const token = crypto.randomBytes(6).toString('hex');
 	const bridge = createBridgeState(widgetRoot);
 	const server = http.createServer((request, response) => {
@@ -162,7 +160,7 @@ async function startWorkspaceServer(options) {
 	server.listen(options.port, '0.0.0.0', () => {
 		const address = server.address();
 		const port = typeof address === 'object' && address ? address.port : options.port;
-		writeBridgeInfo(packageRoot, port, token);
+		writeBridgeInfo(workspaceRoot, port, token);
 		console.log(`Await computer connection serving ${widgetRoot}`);
 		printServerUrls(port, token);
 		console.log('Press Ctrl+C to stop.');
@@ -387,52 +385,34 @@ function widgetPathKey(widgets) {
 	return widgets.map(widget => widget.path).sort((left, right) => left.localeCompare(right)).join('\n');
 }
 
-function findPackageRoot(start) {
+function findBridgeRoot(start) {
 	let current = path.resolve(start);
 	while (true) {
-		const candidate = path.join(current, 'package.json');
-		if (fs.existsSync(candidate)) {
+		if (fs.existsSync(bridgeInfoPath(current))) {
 			return current;
 		}
 
 		const parent = path.dirname(current);
 		if (parent === current) {
-			return null;
+			throw new Error('Cannot find Await bridge info. Run npx await-widget first.');
 		}
 
 		current = parent;
 	}
 }
 
-async function resolveWidgetServerRoots(start) {
-	const widgetRoot = path.resolve(start);
-	const packageRoot = findPackageRoot(widgetRoot);
-	if (
-		!packageRoot
-		|| !hasRuntimeDependency(packageRoot)
-	) {
-		throw new Error(widgetDirectoryError);
-	}
-
-	if (packageRoot === widgetRoot) {
-		return {packageRoot, widgetRoot: await selectWidgetRoot(packageRoot)};
-	}
-
-	if (path.dirname(widgetRoot) !== packageRoot || !isValidTopLevelName(path.basename(widgetRoot))) {
-		throw new Error(widgetDirectoryError);
-	}
-
-	return {packageRoot, widgetRoot};
-}
-
-function selectWidgetRoot(packageRoot) {
+function selectWidgetRoot(directory) {
 	const options = [
-		{name: `${path.basename(packageRoot)} (root)`, path: packageRoot},
-		...fs.readdirSync(packageRoot, {withFileTypes: true})
-			.filter(entry => entry.isDirectory() && isValidTopLevelName(entry.name))
+		{name: `${path.basename(directory)} (current directory)`, path: directory},
+		...fs.readdirSync(directory, {withFileTypes: true})
+			.filter(entry => entry.isDirectory() && isSelectableDirectoryName(entry.name))
 			.sort((left, right) => left.name.localeCompare(right.name))
-			.map(entry => ({name: entry.name, path: path.join(packageRoot, entry.name)})),
+			.map(entry => ({name: entry.name, path: path.join(directory, entry.name)})),
 	];
+	if (options.length === 1) {
+		return directory;
+	}
+
 	let selected = 0;
 	let rendered = false;
 	readline.emitKeypressEvents(process.stdin);
@@ -479,11 +459,6 @@ function selectWidgetRoot(packageRoot) {
 	});
 }
 
-function hasRuntimeDependency(packageRoot) {
-	const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
-	return Boolean(manifest.dependencies?.['@await-widget/runtime'] ?? manifest.devDependencies?.['@await-widget/runtime']);
-}
-
 function listDesktopWidgets(root) {
 	return [{name: path.basename(root), path: singleWidgetPath}];
 }
@@ -518,7 +493,7 @@ function safeWidgetPath(root, widgetPath, options = {}) {
 	return root;
 }
 
-function isValidTopLevelName(name) {
+function isSelectableDirectoryName(name) {
 	return Boolean(name) && !name.includes('/') && !name.includes('\\') && !isExcludedName(name);
 }
 
@@ -766,19 +741,11 @@ function resolveBridgeUrl(options) {
 		return options.bridgeUrl;
 	}
 
-	const root = findPackageRoot(path.resolve(options.workspace ?? process.cwd()));
-	if (!root) {
-		throw new Error('Cannot find package.json for Await bridge lookup.');
-	}
-
+	const root = findBridgeRoot(options.workspace ?? process.cwd());
 	return readBridgeUrl(bridgeInfoPath(root));
 }
 
 function readBridgeUrl(infoPath) {
-	if (!fs.existsSync(infoPath)) {
-		throw new Error('Cannot find Await bridge info. Run npx await-widget first.');
-	}
-
 	const info = JSON.parse(fs.readFileSync(infoPath, 'utf8'));
 	return info.bridgeUrl;
 }
@@ -812,7 +779,8 @@ function appCommandResult(options, tool, result) {
 }
 
 function saveCapture(options, result) {
-	const root = findPackageRoot(options.workspace ? path.resolve(options.workspace) : process.cwd()) ?? process.cwd();
+	const workspace = path.resolve(options.workspace ?? process.cwd());
+	const root = options.bridgeUrl ? workspace : findBridgeRoot(workspace);
 	const directory = path.join(root, bridgeInfoDirectory, 'captures');
 	const name = safeCaptureFileName(String(result.widgetId ?? 'widget'));
 	const filePath = path.join(directory, `${name}-${Date.now()}.png`);
@@ -1021,14 +989,14 @@ function printHelp() {
   await-widget [--port ${defaultPort}]
   await-widget app <command> [options]
 
-Start the Await computer connection from a package root or first-level widget
-folder whose package.json includes @await-widget/runtime. Starting from the
-package root opens a directory selector.
+Start the Await computer connection from any directory. If it has selectable
+subdirectories, choose the current directory or one of them.
 
 What it does:
   - Serves the selected widget folder to Await for live sync.
   - Prints a URL to paste into Await's Connect Computer sheet.
-  - Writes .await/bridge.json in the package root for app commands.
+  - Writes .await/bridge.json in the directory where the connection was started.
+  - App commands search the current directory and its parents for bridge info.
   - Sends one-shot JSON app commands with await-widget app <command>.
 
 Examples:
@@ -1040,7 +1008,7 @@ Examples:
   npx await-widget app get-recent-widget-logs --widget-id YourWidget
 
 App command options:
-  --workspace <path>     Read .await/bridge.json from another package/widget path.
+  --workspace <path>     Search this directory and its parents for .await/bridge.json.
   --bridge-url <url>     Send directly to a bridge URL instead of reading bridge.json.
   --json <json>          Merge raw JSON arguments into the app command.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@await-widget/runtime",
-	"version": "0.0.48",
+	"version": "0.0.50",
 	"description": "TypeScript declarations for Await widgets.",
 	"license": "MIT",
 	"author": "Maundy",

package/types/await.d.ts

@@ -10,293 +10,305 @@ declare module 'await' {
 		props: Props,
 	) => NativeView;
 	/** This is an experimental component and may change in the future. */
-	export function Scroll(
+	export const Scroll: (
 		props: ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
-	export function VStack(
+	) => NativeView;
+	export const VStack: (
 		props: VStackValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
-	export function HStack(
+	) => NativeView;
+	export const HStack: (
 		props: HStackValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
-	export function Flow(
+	) => NativeView;
+	export const Flow: (
 		props: FlowValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
-	export function ZStack(
+	) => NativeView;
+	export const ZStack: (
 		props: ZStackValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Opens a custom-scheme URL or universal link through the Await app when tapped. */
-	export function Link(
+	export const Link: (
 		props: LinkValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
 	/** When tapped, runs an intent or opens a universal link directly without going through the Await app. */
-	export function Button(
+	export const Button: (
 		props: ButtonValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays a solid color and expands to fill the available space. */
-	export function Color(
+	export const Color: (
 		props: ColorValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays text and can contain nested `Text` or `Image` views. */
-	export function Text(
+	export const Text: (
 		props: TextValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
+	/**
+Displays text in a fixed area, or as a rendered image when fontURL is set.
+Without lines, lays out as much text as fits in the fixed area.
+Supplied lines are drawn directly, including an empty array that draws no lines.
+*/
+	export const TextRender: (
+		props: TextRenderValue &
+			ID &
+			Mods & {
+				children?: never;
+			},
+	) => NativeView;
 	/** Displays an automatically updating clock, countdown/count-up timer, or stopwatch. */
-	export function Time(
+	export const Time: (
 		props: TimeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
-	export function ProgressView(
+	) => NativeView;
+	export const ProgressView: (
 		props: ProgressViewValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
-	export function Gauge(
+	) => NativeView;
+	export const Gauge: (
 		props: GaugeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays an image from a local or remote path, or renders child views as an image. Avoid large or complex child content due to system limits. */
-	export function Image(
+	export const Image: (
 		props: ImageValue &
 			ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays a system SF Symbol. */
-	export function Icon(
+	export const Icon: (
 		props: IconValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays an SVG from a local or remote path, or from raw SVG markup. */
-	export function Svg(
+	export const Svg: (
 		props: SvgValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a rounded rectangle that expands to fill the available space. */
-	export function RoundedRectangle(
+	export const RoundedRectangle: (
 		props: RoundedRectangleValue &
 			ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a rounded rectangle with independently configurable corners that expands to fill the available space. */
-	export function UnevenRoundedRectangle(
+	export const UnevenRoundedRectangle: (
 		props: UnevenRoundedRectangleValue &
 			ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a rectangle that expands to fill the available space. */
-	export function Rectangle(
+	export const Rectangle: (
 		props: ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a circular sector that expands to fill the available space. */
-	export function Sector(
+	export const Sector: (
 		props: SectorValue &
 			ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws an ellipse that expands to fill the available space. */
-	export function Ellipse(
+	export const Ellipse: (
 		props: ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a circle that expands to fill the available space. */
-	export function Circle(
+	export const Circle: (
 		props: ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a polygon that expands to fill the available space. */
-	export function Polygon(
+	export const Polygon: (
 		props: PolygonValue &
 			ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a diamond that expands to fill the available space. */
-	export function Diamond(
+	export const Diamond: (
 		props: ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Draws a capsule that expands to fill the available space. */
-	export function Capsule(
+	export const Capsule: (
 		props: CapsuleValue &
 			ShapeValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Adds flexible space within an `HStack` or `VStack`, expanding to fill the available space. */
-	export function Spacer(
+	export const Spacer: (
 		props: SpacerValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
-	export function Group(
+	) => NativeView;
+	export const Group: (
 		props: ID &
 			Mods & {
 				children?: NativeView;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a modifier for use in a `CustomButtonStyle`. */
-	export function Modifier(
+	export const Modifier: (
 		props: ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
-	export function EmptyView(
+	) => NativeView;
+	export const EmptyView: (
 		props: ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a transparent button that expands to fill the available space. */
-	export function FullButton(
+	export const FullButton: (
 		props: ButtonValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Displays a random number for debugging. */
-	export function Stamp(
+	export const Stamp: (
 		props: ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a vertical page-flip effect. */
-	export function VFlip(
+	export const VFlip: (
 		props: FlipValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a horizontal page-flip effect. */
-	export function HFlip(
+	export const HFlip: (
 		props: FlipValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a flip transition around the x-axis. */
-	export function XFlip(
+	export const XFlip: (
 		props: AxisFlipValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a flip transition around the y-axis. */
-	export function YFlip(
+	export const YFlip: (
 		props: AxisFlipValue &
 			ID &
 			Mods & {
 				children?: never;
 			},
-	): NativeView;
+	) => NativeView;
 	/** Creates a GIF-like animation with limited system support. Only specific durations are available, transparency is not supported directly, and frame dimensions and count should remain small. */
-	export function Gif(
+	export const Gif: (
 		props: GifValue &
 			ID &
 			Mods & {
 				children: NativeView[];
 			},
-	): NativeView;
+	) => NativeView;
 	/** Cycles through a sequence of views based on the selected time unit, enabling effects such as a ticking second hand. Available on iOS 26 and later. */
-	export function Ticker(
+	export const Ticker: (
 		props: TickerValue &
 			ID &
 			Mods & {
 				children: NativeView[];
 			},
-	): NativeView;
+	) => NativeView;
 	/** Flashes once per second in a 60-second cycle, achieving the effect of a ticking second hand. Available on iOS 18 and later. */
-	export function FlashTicker(
+	export const FlashTicker: (
 		props: FlashTickerValue &
 			ID &
 			Mods & {
 				children: NativeView[];
 			},
-	): NativeView;
+	) => NativeView;
 }
 
 declare module 'await/jsx-runtime' {

package/types/bridge.d.ts

@@ -14,6 +14,13 @@ export declare function setInterval(
 export declare function sleep(ms: number): Promise<void>;
 export declare function clearInterval(timerID: unknown): void;
 export declare function print(...args: unknown[]): void;
+/**
+Returns whether two acyclic Encodable values are equal.
+Records compare their own enumerable string keys, ignoring key order and distinguishing missing keys from undefined values.
+Arrays compare their length and elements in order; empty slots are treated as undefined.
+Primitive values use strict equality, except that NaN equals NaN.
+*/
+export declare function compare(lhs: Encodable, rhs: Encodable): boolean;
 export declare const console: {
 	log(...args: unknown[]): void;
 };
@@ -104,6 +111,16 @@ export declare const AwaitFile: {
 		pages: number[],
 		pageSize: number,
 	): Array<string | undefined>;
+	renderText(
+		path: string,
+		request: TextRenderRequest,
+		layout: TextRenderLayout,
+	): TextRenderResult | undefined;
+	renderTexts(
+		path: string,
+		requests: TextRenderRequest[],
+		layout: TextRenderLayout,
+	): Array<TextRenderResult | undefined> | undefined;
 	saveUIRenderImage(path: string, value: NativeView): void;
 };
 export declare const AwaitAudio: {
@@ -215,6 +232,7 @@ declare global {
 	const AwaitFile: AwaitFileGlobal;
 	const AwaitAudio: AwaitAudioGlobal;
 	function print(...args: unknown[]): void;
+	function compare(lhs: Encodable, rhs: Encodable): boolean;
 	const sleep: SleepGlobal;
 }
 export {};

package/types/meta.d.ts

@@ -14,17 +14,31 @@ type ProgressViewStyle = 'automatic' | 'linear' | 'circular';
 
 type Material = 'regular' | 'thin' | 'thick' | 'ultraThin' | 'ultraThick';
 
+type Hierarchical =
+	| 'primary'
+	| 'secondary'
+	| 'tertiary'
+	| 'quaternary'
+	| 'quinary';
+
+type ShapeStyleEffects = {
+	/**
+	Applies Apple's native inner shadow to this style.
+	Uses the source alpha; fully transparent fills do not produce a visible inner shadow.
+	Shadow color defaults to black at 33% opacity; blur, x, and y default to 0.
+	*/
+	innerShadow?: Shadow;
+};
+
+/** The strings primary and secondary resolve as hierarchical styles in ShapeStyle positions. */
 type ShapeStyle =
 	| Color
 	| Material
+	| Hierarchical
 	| LinearGradient
 	| RadialGradient
 	| AngularGradient
-	| 'primary'
-	| 'secondary'
-	| 'tertiary'
-	| 'quaternary'
-	| 'quinary';
+	| ({style: Color | Material | Hierarchical} & ShapeStyleEffects);
 
 type NativeAnimation = (
 	| {
@@ -127,7 +141,7 @@ type RadialGradient = {
 	stops?: Array<[Color, number]>;
 	startRadius?: number;
 	endRadius?: number;
-};
+} & ShapeStyleEffects;
 
 type AngularGradient = {
 	gradient: 'angular';
@@ -136,7 +150,7 @@ type AngularGradient = {
 	stops?: Array<[Color, number]>;
 	angle?: number;
 	center?: UnitPoint;
-};
+} & ShapeStyleEffects;
 
 type LinearGradient = {
 	gradient: 'linear';
@@ -145,7 +159,7 @@ type LinearGradient = {
 	stops?: Stop[];
 	startPoint?: UnitPoint;
 	endPoint?: UnitPoint;
-};
+} & ShapeStyleEffects;
 
 type UnitPoint =
 	| 'center'
@@ -506,3 +520,13 @@ type DateFormatToken =
 	| DateFormatFractionalSecondToken
 	| DateFormatAMPMToken
 	| DateFormatTimeZoneToken;
+
+type ImageStroke = {
+	color: Color;
+	/**
+		Outward width in points at the decoded image's natural size. Must be nonnegative.
+		Adds transparent space around the image; the image and stroke then resize together.
+		proposedSize includes the added space. Template rendering also recolors the stroke.
+		*/
+	width: number;
+};

package/types/model.d.ts

@@ -429,3 +429,56 @@ type Timeline<T extends Record<string, unknown> = Record<string, unknown>> = {
 	update?: Update;
 	skipOnPlayingNote?: boolean;
 };
+
+type TextRenderLayout = {
+	width: number;
+	height: number;
+	fontSize: number;
+	fontWeight?: number;
+	fontWidth?: number;
+	lineHeight?: number;
+	lineSpacing?: number;
+	tracking?: number;
+	kerning?: number;
+	horizontalAlignment?: TextAlignment;
+	verticalAlignment?: 'top' | 'center' | 'bottom';
+} & (
+	| {
+			fontURL: string;
+			fontName?: never;
+			fontDesign?: FontDesign;
+	  }
+	| {
+			fontName: string;
+			fontURL?: never;
+			fontDesign?: FontDesign;
+	  }
+	| {
+			fontURL?: never;
+			fontName?: never;
+			fontDesign?: FontDesign;
+	  }
+);
+
+type TextRenderRequest = {
+	offset: number;
+	forward: boolean;
+};
+
+type TextRenderLine = {
+	range: [start: number, end: number];
+	baseline: number;
+};
+
+type TextRenderInput = TextRenderLayout & {
+	text: string;
+	lines?: TextRenderLine[];
+};
+
+type TextRenderResult = TextRenderLayout & {
+	text: string;
+	lines: TextRenderLine[];
+	startOffset: number;
+	endOffset: number;
+	totalBytes: number;
+};

package/types/prop.d.ts

@@ -117,6 +117,11 @@ type TextValue = {
 	value?: Encodable;
 };
 
+type TextRenderValue = {
+	value: TextRenderInput;
+	fill?: ShapeStyle;
+};
+
 type GaugeValue = {
 	/** Number value in range 0~1. */
 	value?: number;
@@ -125,6 +130,8 @@ type GaugeValue = {
 type ImageValue = {
 	/** Local or remote path such as `img.png` `path/img.png` `https://example.com/img.png` */
 	url?: string;
+	/** Adds a round outer stroke along the image's alpha contour, including transparent holes. */
+	stroke?: ImageStroke;
 	/** The modes used to resize an image to fit within its containing view. */
 	resizable?: Resizable;
 	/** The level of quality for rendering an image that requires interpolation, such as a scaled image. */
@@ -133,7 +140,7 @@ type ImageValue = {
 	style?: TemplateRenderingMode;
 	/** The mode that indicates how images are rendered on widget accented mode */
 	accented?: Accented;
-	/** The maximum number of pixels along the image's longest edge. Defaults to 1000. */
+	/** Decimals are truncated toward zero; negative values become 0. Positive integers limit image area to approximately maxPixel squared pixels. Use 0 for no limit, preserving source pixel dimensions. Defaults to 1000. */
 	maxPixel?: number;
 	/** Maximum width and height for the image's natural layout size. Scales down proportionally. */
 	proposedSize?: {width?: number; height?: number};
@@ -344,6 +351,7 @@ type BaseMods = {
 		  };
 	saturation?: number;
 	scaleEffect?: ScaleEffect;
+	/** Ordinary outer shadow. For an inner shadow, set innerShadow on a ShapeStyle. */
 	shadow?: Shadow;
 	sides?: number;
 	strikethrough?: