@yodaos-pkg/aix 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -30,7 +30,134 @@ async function fromFile(file: File) {
30
30
  }
31
31
  ```
32
32
 
33
- ## Using the Package Lab
33
+ ## WASM Loading
34
+
35
+ By default, `AIX.From()` and all instance methods initialize a separate reader-only WASM.
36
+ They do not load image codecs, script minification, or source/schema checking.
37
+ The optional `AIX.From(data, limits, true)` check also loads the full tooling module.
38
+ The first pack, optimize, or source-check call lazily loads the full module;
39
+ concurrent tooling calls share initialization. Existing reader instances remain
40
+ valid after tooling loads, and tooling-only calls do not fetch reader WASM.
41
+
42
+ The generated distribution includes `pkg-reader/` and `pkg/`; self-host both
43
+ with their adjacent JS/WASM files. The existing raw `pkg/aix_web.js` exports
44
+ remain complete and the npm CLI keeps its synchronous full Node.js bundle.
45
+ Rust builds default to the `tooling` feature; `--no-default-features` produces
46
+ reader exports without the packer dependency. `npm run build` builds both web
47
+ artifacts; `npm run build:wasm:reader` builds only the reader artifact.
48
+
49
+ Local measurements reduced reader WASM from 5,514,021 to 355,365 bytes. Mixed
50
+ reader/tooling workflows load both binaries and retain two module memories.
51
+ See the repository's `docs/wasm.md` for baseline samples, timing limits, the
52
+ compatibility plan, and reproduction commands.
53
+
54
+ ## Archive Resource Limits
55
+
56
+ Pass caller-selected budgets when reading untrusted packages:
57
+
58
+ ```typescript
59
+ const aix = await AIX.From(file, {
60
+ maxEntries: 1024,
61
+ maxEntryBytes: 8 * 1024 * 1024,
62
+ maxTotalBytes: 32 * 1024 * 1024,
63
+ });
64
+ ```
65
+
66
+ All limits are inclusive non-negative safe integers. Directories and signature
67
+ metadata count too. Metadata is rejected before extraction if over budget;
68
+ extraction also bounds output and retains CRC and size checks. `maxTotalBytes`
69
+ is the sum of declared uncompressed sizes, not a cumulative read budget.
70
+ Zero allows no entries or bytes. Omitted fields and the original `AIX.From(data)`
71
+ call remain unlimited for compatibility; set all three limits for untrusted
72
+ packages. The input archive buffer, parsed objects, and retained copies need
73
+ separate budgets. This policy applies to readers, not `AIX.optimize`.
74
+
75
+ Direct WASM consumers can call `AixReaderWasm.with_limits(data, limits)` using
76
+ the same fields. The existing `new AixReaderWasm(data)` constructor is unchanged.
77
+
78
+ ## Open and Check
79
+
80
+ Pass `true` as the third `AIX.From` argument to run the source checker before
81
+ receiving the package. The second argument remains the optional read limits;
82
+ pass `undefined` there when no limits are needed.
83
+
84
+ ```typescript
85
+ import { AIX, AixCheckError } from '@yodaos-pkg/aix';
86
+
87
+ async function openCheckedPackage(file: File) {
88
+ try {
89
+ return await AIX.From(file, undefined, true);
90
+ } catch (error) {
91
+ if (error instanceof AixCheckError) console.table(error.diagnostics);
92
+ throw error;
93
+ }
94
+ }
95
+ ```
96
+
97
+ Warnings alone pass. Error diagnostics reject with the exported `AixCheckError`
98
+ (`name: 'AixCheckError'`), an `Error` subclass with the complete `CheckReport` in
99
+ `report` and the same diagnostic array in `diagnostics`, including warnings.
100
+ The check uses `checkFromSource` on the package's source files without running
101
+ project code. It adds work and retains extracted check inputs; read limits still
102
+ apply but do not bound total checker memory. Archive, extraction, loading, and
103
+ collection failures retain their original operation errors rather than a check
104
+ report. Omitting the third argument or passing `false` preserves the existing
105
+ reader-only behavior.
106
+
107
+ ## Check Source Files
108
+
109
+ The Web SDK and npm CLI use the same complete in-memory check engine:
110
+
111
+ ```typescript
112
+ import { AIX, type CheckReport } from '@yodaos-pkg/aix';
113
+
114
+ const encode = (source: string) => new TextEncoder().encode(source);
115
+ const report: CheckReport = await AIX.checkFromSource([
116
+ { path: 'app.json', data: encode('{"pages":[]}') },
117
+ { path: 'main.ts', data: encode('const count: number = ;') },
118
+ ], { onProgress: (event) => console.log(event.type) });
119
+ console.log(report.diagnostics); // AIX029: invalid TypeScript syntax at main.ts:1
120
+
121
+ // Files from an <input type="file" webkitdirectory> selection also work.
122
+ const fileReport = await AIX.checkFromFiles(Array.from(input.files ?? []));
123
+ ```
124
+
125
+ Checks cover JSON/config validity, Page/Widget structure, component references
126
+ and cycles, JS/TS syntax, statically recognizable permissions, and Page JSON Schemas. Each diagnostic has `code`, `severity`, `path`,
127
+ `line`, `column`, and `message`. Source errors are returned in the report;
128
+ invalid input paths or collection failures reject the promise.
129
+
130
+ `checkFromSource` takes paths relative to the application root. `checkFromFiles`
131
+ uses `webkitRelativePath`, removing the selected directory's outer folder.
132
+ Both apply nested `.aixignore` rules and exclude local `.aix` caches. The shared
133
+ check adapter loads only when checking is first requested. It uses the WASM
134
+ engine without a Node filesystem, Node polyfills, or dependency downloads.
135
+ The same API also works in a Web Worker.
136
+
137
+ Both methods accept `CheckOptions` with an optional `onProgress` callback.
138
+ `CheckProgressEvent` reports checker loading, source/schema validation (input
139
+ file count), and diagnostic collection. These are stage notifications, not a
140
+ percentage estimate. Browser checks are synchronous after loading; run the API
141
+ in a Web Worker to keep a browser progress display responsive.
142
+
143
+ `check_finished` events carry an exported `CheckResult` with `id`, `label`,
144
+ `status` (`passed`, `warning`, `failed`, or `skipped`), `errors`, `warnings`, and
145
+ an optional `detail` explaining incomplete/skipped checks. The CLI uses the same
146
+ results for its final checklist. The returned `CheckReport` remains a diagnostic
147
+ report, so JSON callers do not need to parse terminal output.
148
+
149
+ JavaScript and TypeScript are syntax-checked, including `.ts`, `.mts`, `.cts`,
150
+ and Ink `<script lang="ts">` blocks. Inline diagnostics retain their original
151
+ Ink file locations. TypeScript semantic, import-resolution, and compiler-option
152
+ checks are currently excluded. No type environment is loaded, and checks do not
153
+ emit or run code.
154
+
155
+ Page `schema.data` is validated against `$schema` (2020-12 by default), including
156
+ nested keywords, patterns, and local references. Missing/null schemas remain
157
+ accepted. External schema resources are not fetched. These checks validate
158
+ schema declarations, not runtime data; packing and reader semantics are unchanged.
159
+
160
+ ## Using Play
34
161
 
35
162
  The official browser lab now lives in the docs site at `/play`.
36
163
 
@@ -79,7 +206,7 @@ This is useful for verifying whether `app.json`, page schemas, and `getTools()`
79
206
  ### Pack and Optimize
80
207
 
81
208
  The Web package includes the same in-memory packer and pure Rust resource
82
- optimizer as the native CLI:
209
+ optimizer used by the npm CLI:
83
210
 
84
211
  ```ts
85
212
  const packed = await AIX.pack(
@@ -121,8 +248,10 @@ files and wants to invoke the low-level packer directly.
121
248
 
122
249
  The main class to interact with an AIX package.
123
250
 
124
- #### `static async From(data: Uint8Array | File): Promise<AIX>`
251
+ #### `static async From(data: Uint8Array | File, limits?: AixReadLimits, check?: boolean): Promise<AIX>`
125
252
  Initializes the WASM module and creates an AIX instance from the given `.aix` file content. It supports both `Uint8Array` and the standard Web `File` object.
253
+ `check` defaults to `false`. Set it to `true` to check before returning and reject
254
+ with `AixCheckError` when errors are reported; see [Open and Check](#open-and-check).
126
255
  ```typescript
127
256
  // From Uint8Array
128
257
  const aix = await AIX.From(new Uint8Array(buffer));
@@ -157,6 +286,17 @@ Extracts the navigation bar title from the `app.json`.
157
286
  const title = aix.getTitle();
158
287
  ```
159
288
 
289
+ #### `getPermissions(): string[]`
290
+ Returns the permission names declared in `app.json.permissions`, preserving their
291
+ order, duplicates, and custom names. An omitted or empty list returns `[]`.
292
+ Throws if `app.json` is missing, unreadable, invalid, or `permissions` is not an
293
+ array of strings. This reads declarations without querying authorization or
294
+ prompting for access.
295
+ ```typescript
296
+ const permissions = aix.getPermissions();
297
+ // e.g. ['GEOLOCATION', 'CAMERA']
298
+ ```
299
+
160
300
  #### `getPages(): PageInfo[]`
161
301
  Returns information about all pages defined in the package, including their paths, titles, and data schemas.
162
302
  ```typescript
@@ -165,18 +305,52 @@ const pages = aix.getPages();
165
305
  [{
166
306
  name: "pages/index/index",
167
307
  title: "Home",
168
- data_schema: { ... }
308
+ description: null,
309
+ data_schema: { ... },
310
+ size: { width: 480, height: 168 }
169
311
  }]
170
312
  */
171
313
  ```
172
314
 
173
- #### `getWidgets(): WidgetInfo[]`
174
- Returns widget declarations after verifying that every path resolves to an `.ink` entry in the package. Throws when a declared entry is missing.
315
+ #### `getWidgets(locale?): WidgetInfo[]`
316
+ Returns widget declarations after verifying that every path resolves to an `.ink` entry in the package. When `locale` is provided, merges `displayName` and `description` from the matching `app.<locale>.json` overlay. Throws when a declared entry is missing or the selected locale file is invalid.
317
+ ```typescript
318
+ const widgets = aix.getWidgets('en-US');
319
+ // [{ path: "widgets/clock/index", family: "1x1", placement: "persistent", displayName: "Clock", description: "Shows the current time." }]
320
+ ```
321
+
322
+ #### `resolveMetadata(): MetadataResolution`
323
+
324
+ Returns `{ pages, tools, diagnostics }` synchronously. Missing/unreadable resources,
325
+ UTF-8 errors, and malformed page metadata produce `{ path, message }` diagnostics,
326
+ one per failed page. Failed pages are excluded from both result lists; other
327
+ pages retain declaration order. A valid empty page list has no diagnostics;
328
+ invalid/unreadable `app.json.pages` produces an `app.json` diagnostic.
329
+
175
330
  ```typescript
176
- const widgets = aix.getWidgets();
177
- // [{ path: "widgets/clock/index", family: "1x1", placement: "persistent" }]
331
+ const result = aix.resolveMetadata();
332
+ console.log(result.diagnostics);
333
+ const tools = result.tools; // only successfully resolved pages
334
+ // For all-or-nothing acceptance, require result.diagnostics.length === 0.
178
335
  ```
179
336
 
337
+ This API requires readable `.ink`, or both `.json` and `.wxml` for traditional
338
+ pages, and checks ZIP integrity and UTF-8 for resources it reads. It deserializes
339
+ page JSON and complete Ink `<script def>` blocks. Optional definitions, schemas,
340
+ and styles may be absent; present styles must be readable (`.wcss` before `.wxss`).
341
+ A broken Ink entry never falls back to traditional files. Use source checking
342
+ for full syntax, component, and JSON Schema validation. Runtime execution and
343
+ packing validation are unchanged.
344
+
345
+ `getPages()`/`getTools()` remain tolerant and can return default metadata/tools
346
+ even for missing resources. Page, Widget, and title fields are parsed separately;
347
+ invalid Widget fields no longer hide valid pages. `getWidgets()` still reports
348
+ Widget errors. Direct WASM consumers use `reader.resolve_metadata()`.
349
+
350
+ Exported `MetadataResolution` has `pages: PageInfo[]`, `tools: Tool[]`, and
351
+ `diagnostics: MetadataDiagnostic[]`; `MetadataDiagnostic` has `path` and `message`
352
+ string fields.
353
+
180
354
  #### `getTools(): Tool[]`
181
355
  Generates a list of OpenAI-compatible tool definitions based on the pages and their schemas.
182
356
  ```typescript
@@ -184,6 +358,8 @@ const tools = aix.getTools();
184
358
  /*
185
359
  [{
186
360
  type: "function",
361
+ target: "_blank",
362
+ layout: { width: 480, height: 168 },
187
363
  function: {
188
364
  name: "pages_index_index",
189
365
  description: "Home",
@@ -204,12 +380,28 @@ interface AixEntry {
204
380
  }
205
381
  ```
206
382
 
383
+ ### JSON and layout types
384
+ ```typescript
385
+ type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
386
+ interface JsonObject { [key: string]: JsonValue }
387
+ type JsonSchema = JsonValue;
388
+ interface PageConstraint { width: number; height: number }
389
+ type ToolTarget = '_current' | '_blank';
390
+ type WidgetPlacement = 'persistent' | 'overlay';
391
+ ```
392
+
393
+ `JsonSchema` retains arbitrary JSON, including boolean schemas and unvalidated
394
+ legacy values. Use `AIX.checkFromSource()` for schema validation. Page `size`
395
+ and tool `layout` both contain numeric width/height constraints.
396
+
207
397
  ### `PageInfo`
208
398
  ```typescript
209
399
  interface PageInfo {
210
400
  name: string;
211
- title?: string;
212
- data_schema: any;
401
+ title: string | null;
402
+ description: string | null;
403
+ data_schema: JsonSchema;
404
+ size: PageConstraint;
213
405
  }
214
406
  ```
215
407
 
@@ -218,6 +410,9 @@ interface PageInfo {
218
410
  interface WidgetInfo {
219
411
  path: string;
220
412
  family: string;
413
+ placement: WidgetPlacement;
414
+ displayName: string | null;
415
+ description: string | null;
221
416
  }
222
417
  ```
223
418
 
@@ -226,14 +421,25 @@ OpenAI compatible tool format.
226
421
  ```typescript
227
422
  interface Tool {
228
423
  type: string;
229
- function: {
230
- name: string;
231
- description?: string;
232
- parameters: any;
233
- };
424
+ target: ToolTarget;
425
+ layout: PageConstraint;
426
+ function: FunctionDefinition;
427
+ }
428
+ interface FunctionDefinition {
429
+ name: string;
430
+ description: string | null;
431
+ parameters: JsonSchema;
234
432
  }
235
433
  ```
236
434
 
435
+ Metadata fields above are always present. Missing strings and nested JSON null
436
+ values now remain `null` through raw WASM, SDK getters, and `resolveMetadata()`,
437
+ matching native Rust JSON. Earlier WASM builds returned `undefined` for these
438
+ values; update explicit `=== undefined` checks to `=== null` when migrating
439
+ metadata consumers. Standalone `getTitle()` and `getVersion()` retain their
440
+ `string | undefined` return type. Tools currently emit `type: "function"` and
441
+ underscore-prefixed targets; `current`/`blank` are input aliases only.
442
+
237
443
  ## Build
238
444
 
239
445
  To build the library for distribution:
@@ -0,0 +1,7 @@
1
+ import type { CheckEngine, CheckOptions, CheckReport } from './types.js';
2
+ export type { CheckDiagnostic, CheckOptions, CheckProgressEvent, CheckReport, CheckResult } from './types.js';
3
+ /** The complete check pipeline shared by the Web SDK and npm CLI. */
4
+ export declare function checkSource(files: {
5
+ path: string;
6
+ data: Uint8Array;
7
+ }[], engine: CheckEngine, options?: CheckOptions): CheckReport;
package/check/index.js ADDED
@@ -0,0 +1,69 @@
1
+ // ts/check/results.ts
2
+ function sourceResults(prepared) {
3
+ let { coverage, report } = prepared, groups = /* @__PURE__ */ new Map();
4
+ for (let diagnostic of report.diagnostics) {
5
+ let id = sourceCategory(diagnostic.code), group = groups.get(id);
6
+ group || groups.set(id, group = []), group.push(diagnostic);
7
+ }
8
+ let blocked = coverage.structure ? void 0 : "app.json could not be validated", inputErrors = groups.get("json")?.some((diagnostic) => diagnostic.severity === "error"), syntaxErrors = groups.get("syntax")?.some((diagnostic) => diagnostic.severity === "error");
9
+ return [
10
+ result(
11
+ "json",
12
+ `JSON syntax and text encoding (${count(coverage.text_files, "file")})`,
13
+ groups.get("json"),
14
+ coverage.text_files ? void 0 : "no text source files"
15
+ ),
16
+ result(
17
+ "structure",
18
+ "App, Page, Widget, and component structure",
19
+ groups.get("structure"),
20
+ blocked ?? (inputErrors ? "some source files could not be parsed" : void 0)
21
+ ),
22
+ result(
23
+ "syntax",
24
+ `JS/TS syntax (${count(coverage.scripts, "script")})`,
25
+ groups.get("syntax"),
26
+ blocked ?? (coverage.scripts ? void 0 : "no scripts to check")
27
+ ),
28
+ result(
29
+ "permissions",
30
+ "Permission declarations and direct API use",
31
+ groups.get("permissions"),
32
+ blocked ?? (inputErrors || syntaxErrors ? "some source files could not be parsed" : void 0)
33
+ ),
34
+ result(
35
+ "schemas",
36
+ `Page JSON Schemas (${count(coverage.schemas, "schema")})`,
37
+ groups.get("schemas"),
38
+ blocked ?? (coverage.schemas ? void 0 : "no Page schemas checked")
39
+ )
40
+ ];
41
+ }
42
+ function result(id, label, diagnostics = [], detail) {
43
+ let errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length, warnings = diagnostics.length - errors;
44
+ return {
45
+ id,
46
+ label,
47
+ errors,
48
+ warnings,
49
+ status: errors ? "failed" : warnings ? "warning" : detail ? "skipped" : "passed",
50
+ ...detail ? { detail } : {}
51
+ };
52
+ }
53
+ function sourceCategory(code) {
54
+ return ["AIX001", "AIX002", "AIX014"].includes(code) ? "json" : ["AIX006", "AIX007", "AIX027", "AIX028", "AIX033", "AIX037", "AIX038"].includes(code) ? "permissions" : code === "AIX029" ? "syntax" : ["AIX031", "AIX047"].includes(code) ? "schemas" : "structure";
55
+ }
56
+ function count(value, unit) {
57
+ return `${value} ${unit}${value === 1 ? "" : "s"}`;
58
+ }
59
+
60
+ // ts/check/index.ts
61
+ function checkSource(files, engine, options = {}) {
62
+ options.onProgress?.({ type: "checking_sources", fileCount: files.length });
63
+ let prepared = engine.prepare_aix_check(files);
64
+ for (let check of sourceResults(prepared)) options.onProgress?.({ type: "check_finished", check });
65
+ return options.onProgress?.({ type: "collecting_diagnostics" }), prepared.report;
66
+ }
67
+ export {
68
+ checkSource
69
+ };
@@ -0,0 +1,48 @@
1
+ export interface CheckDiagnostic {
2
+ code: string;
3
+ severity: 'error' | 'warning';
4
+ path: string;
5
+ line: number;
6
+ column: number;
7
+ message: string;
8
+ }
9
+ export interface CheckReport {
10
+ diagnostics: CheckDiagnostic[];
11
+ }
12
+ export interface CheckResult {
13
+ id: 'json' | 'structure' | 'syntax' | 'permissions' | 'schemas';
14
+ label: string;
15
+ status: 'passed' | 'warning' | 'failed' | 'skipped';
16
+ errors: number;
17
+ warnings: number;
18
+ detail?: string;
19
+ }
20
+ export type CheckProgressEvent = {
21
+ type: 'loading_checker';
22
+ } | {
23
+ type: 'checking_sources';
24
+ fileCount: number;
25
+ } | {
26
+ type: 'check_finished';
27
+ check: CheckResult;
28
+ } | {
29
+ type: 'collecting_diagnostics';
30
+ };
31
+ export interface CheckOptions {
32
+ onProgress?: (event: CheckProgressEvent) => void;
33
+ }
34
+ export interface PreparedCheck {
35
+ report: CheckReport;
36
+ coverage: {
37
+ text_files: number;
38
+ structure: boolean;
39
+ scripts: number;
40
+ schemas: number;
41
+ };
42
+ }
43
+ export interface CheckEngine {
44
+ prepare_aix_check(files: {
45
+ path: string;
46
+ data: Uint8Array;
47
+ }[]): PreparedCheck;
48
+ }
package/check/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/index.d.ts CHANGED
@@ -1,3 +1,12 @@
1
+ import type { CheckDiagnostic, CheckOptions, CheckReport } from './check/types.js';
2
+ export type { CheckDiagnostic, CheckOptions, CheckProgressEvent, CheckReport, CheckResult } from './check/types.js';
3
+ /** A package failed the optional source check in AIX.From(). */
4
+ export declare class AixCheckError extends Error {
5
+ readonly report: CheckReport;
6
+ constructor(report: CheckReport);
7
+ /** All check diagnostics, including warnings. */
8
+ get diagnostics(): CheckDiagnostic[];
9
+ }
1
10
  export interface AixInputFile {
2
11
  path: string;
3
12
  data: Uint8Array;
@@ -29,6 +38,8 @@ export interface PackResult {
29
38
  }
30
39
  export interface PackOptions {
31
40
  buildId?: string;
41
+ /** Stable normalized project ID; reuse across builds. */
42
+ agentId?: string;
32
43
  engine?: string;
33
44
  optimize?: false | OptimizeOptions;
34
45
  }
@@ -54,32 +65,84 @@ export interface AixEntry {
54
65
  size: number;
55
66
  compressed_size: number;
56
67
  }
68
+ /** Inclusive archive budgets. Omitted fields are unlimited for compatibility. */
69
+ export interface AixReadLimits {
70
+ /** Maximum central-directory entries, including directories and metadata. */
71
+ maxEntries?: number;
72
+ /** Maximum declared and extracted bytes per entry. */
73
+ maxEntryBytes?: number;
74
+ /** Maximum total declared uncompressed bytes; repeated reads do not consume it. */
75
+ maxTotalBytes?: number;
76
+ }
77
+ /** JSON returned by the reader, including unvalidated legacy schema values. */
78
+ export type JsonValue = null | boolean | number | string | JsonValue[] | JsonObject;
79
+ export interface JsonObject {
80
+ [key: string]: JsonValue;
81
+ }
82
+ /** Schema payloads retain any JSON value; source checking validates the schema. */
83
+ export type JsonSchema = JsonValue;
84
+ export interface PageConstraint {
85
+ width: number;
86
+ height: number;
87
+ }
57
88
  export interface PageInfo {
58
89
  name: string;
59
- title?: string;
60
- data_schema: any;
90
+ title: string | null;
91
+ description: string | null;
92
+ data_schema: JsonSchema;
93
+ size: PageConstraint;
94
+ }
95
+ export interface MetadataDiagnostic {
96
+ /** Archive path of the missing, unreadable, or malformed resource. */
97
+ path: string;
98
+ message: string;
99
+ }
100
+ export interface MetadataResolution {
101
+ pages: PageInfo[];
102
+ tools: Tool[];
103
+ /** One failure per unresolved page, or an app.json configuration failure. */
104
+ diagnostics: MetadataDiagnostic[];
61
105
  }
106
+ export type WidgetPlacement = 'persistent' | 'overlay';
62
107
  export interface WidgetInfo {
63
108
  path: string;
64
109
  family: string;
65
- placement: 'persistent' | 'overlay';
110
+ placement: WidgetPlacement;
111
+ displayName: string | null;
112
+ description: string | null;
113
+ }
114
+ /** Serialized output uses the underscore-prefixed names, never input aliases. */
115
+ export type ToolTarget = '_current' | '_blank';
116
+ export interface FunctionDefinition {
117
+ name: string;
118
+ description: string | null;
119
+ parameters: JsonSchema;
66
120
  }
67
121
  export interface Tool {
122
+ /** The reader currently emits "function". */
68
123
  type: string;
69
- function: {
70
- name: string;
71
- description?: string;
72
- parameters: any;
73
- };
124
+ target: ToolTarget;
125
+ layout: PageConstraint;
126
+ function: FunctionDefinition;
74
127
  }
75
128
  export declare class AIX {
76
129
  private reader;
77
130
  private constructor();
131
+ /** Run source structure, JS/TS syntax, schema, and permission checks in memory. */
132
+ static checkFromSource(files: AixInputFile[], options?: CheckOptions): Promise<CheckReport>;
133
+ /** Check a browser directory selection, retaining webkitRelativePath. */
134
+ static checkFromFiles(files: File[], options?: CheckOptions): Promise<CheckReport>;
78
135
  /**
79
136
  * Initialize the WASM module and create an AIX instance from the given data.
80
137
  * @param data The .aix file content as Uint8Array or File
138
+ * @param limits Caller budgets; set all three when accepting untrusted archives.
139
+ * Values must be non-negative safe integers. Without limits, retains the
140
+ * historical unlimited policy. Input bytes and caller-retained copies are
141
+ * outside these budgets.
142
+ * @param check Run the source checker before returning; defaults to false.
143
+ * Error diagnostics reject with AixCheckError; warnings alone are accepted.
81
144
  */
82
- static From(data: Uint8Array | File): Promise<AIX>;
145
+ static From(data: Uint8Array | File, limits?: AixReadLimits, check?: boolean): Promise<AIX>;
83
146
  static pack(files: AixInputFile[], options?: PackOptions): Promise<PackResult>;
84
147
  /**
85
148
  * Packs an in-memory application source tree.
@@ -104,19 +167,34 @@ export declare class AIX {
104
167
  * Get the version metadata from the AIX package.
105
168
  */
106
169
  getVersion(): string | undefined;
170
+ /** Stable project ID from the manifest; undefined for legacy packages. */
171
+ getAgentId(): string | undefined;
107
172
  supportsEngine(currentVersion: string): boolean;
108
173
  /**
109
174
  * Get the title from app.json.
110
175
  */
111
176
  getTitle(): string | undefined;
177
+ /**
178
+ * Get permission names declared in app.json, in declaration order.
179
+ * Missing declarations return []; invalid configuration throws.
180
+ * This does not query runtime or device authorization.
181
+ */
182
+ getPermissions(): string[];
112
183
  /**
113
184
  * Get all pages from app.json and pages/*.json.
114
185
  */
115
186
  getPages(): PageInfo[];
187
+ /**
188
+ * Resolve readable page resources and metadata, excluding failed pages/tools.
189
+ * Inspect diagnostics to distinguish a valid empty result from resolution errors.
190
+ * Widget/title fields are independent. This does not run full source checks.
191
+ */
192
+ resolveMetadata(): MetadataResolution;
116
193
  /**
117
194
  * Get all widgets from app.json after validating that each .ink entry exists.
195
+ * When locale is provided, merge displayName and description from app.<locale>.json.
118
196
  */
119
- getWidgets(): WidgetInfo[];
197
+ getWidgets(locale?: string): WidgetInfo[];
120
198
  /**
121
199
  * Get all tools from app.json and pages/*.json in OpenAI format.
122
200
  */