@meistrari/tela-cli 1.0.0 → 1.1.0

package/dist/docs/workflow-code/api-reference.md

@@ -14,6 +14,7 @@ import {
     build,
     canvas,
     code,
+    crop,
     input,
     llm,
     splitter,
@@ -32,6 +33,8 @@ import type { WorkflowCodeConfig } from '@meistrari/workflow-code'
 | [`input.file()`](#inputfileoptions) | File input supplied by upload or Vault reference. |
 | [`llm()`](#llmoptions) | Single model-call transformation with optional structured output. |
 | [`splitter()`](#splitteroptions) | Splitting file inputs, compatible prior outputs, or existing Vault files. |
+| [`crop()`](#cropoptions) | Cropping selected PDF pages from compatible files or existing Vault files. |
+| [`vault.asset()`](#vaultassetpath-options) | Declaring a local file that `sync` uploads and locks in Vault. |
 | [`vault.ref()`](#vaultrefreference) | Declaring an inert reference to an existing `vault://...` file. |
 | [`remote()`](#remote) | Generated catalog paths and explicit ID refs for inert remote authoring. |
 | [`canvas()`](#canvasremoteref-options) | Executable Canvas or Workflow refs from the remote catalog. |
@@ -390,7 +393,7 @@ type SplitterOptions = {
 function splitter(options: SplitterOptions): SplitterNodeHandle
 ```
 
-Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()`, or an array of Vault refs. It does not accept arbitrary strings or text references.
+Declares the Workflow V3 `document-splitter` action. Its `input.file` is an exclusive reference field: it accepts a compatible workflow file input or previous-node output, one `vault.ref()` or `vault.asset()`, or an array containing one of those Vault declaration kinds. It does not accept arbitrary strings or text references.
 
 | Option | Type | Required | Default | Description |
 | --- | --- | --- | --- | --- |
@@ -471,6 +474,82 @@ const generatedCodePages = splitter({
 
 The referenced runtime value still needs to describe a real file. Declaring `fileUrl` or `vaultReference` in an LLM schema does not upload or create a Vault file.
 
+### `crop(options)`
+
+```ts
+type CropOptions = {
+    name: string
+    key?: string
+    input: {
+        file: WorkflowCodeExclusiveFileSource
+        indexes: readonly (number | string)[]
+        type?: 'pdf'
+    }
+}
+
+function crop(options: CropOptions): CropNodeHandle
+```
+
+Declares Workflow V3's existing `document-cropper` action. Its exclusive `input.file` supports the same compatible workflow input, prior-node output, `vault.ref()`, `vault.asset()`, and Vault-array forms as `splitter.input.file`.
+
+| Option | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Display name and fallback node identity. |
+| `key` | `string` | No | `name` | Stable identity when the display name may change. |
+| `input.file` | `WorkflowCodeExclusiveFileSource` | Yes | — | File/File-array workflow reference, `vault.ref()`, `vault.asset()`, or an array of Vault declarations. |
+| `input.indexes` | `readonly (number \| string)[]` | Yes | — | Integer page indexes or cropper-supported ranges such as `'3-5'`. |
+| `input.type` | `'pdf'` | No | `'pdf'` | Cropper document type. |
+
+```ts
+const selectedPages = crop({
+    name: 'Crop selected invoice pages',
+    input: {
+        file: ({ ref }) => ref(invoice),
+        indexes: [1, '3-5'],
+    },
+})
+
+const cropAgain = crop({
+    name: 'Crop prior result',
+    input: {
+        file: ({ ref, paths }) => ref(selectedPages, paths(selectedPages)[0].file),
+        indexes: [2],
+    },
+})
+```
+
+The result is a typed array whose items contain `indexes`, `originalFile`, and `file`. Compile validates file compatibility before lowering input and previous-node refs to Workflow V3 URIs; direct Vault refs lower to the cropper's transport-file shape. Source evaluation and offline compilation do not contact Vault or invoke prior nodes.
+
+### `vault.asset(path, options?)`
+
+```ts
+const vault: {
+    asset: (
+        path: string,
+        options?: { name?: string, mimeType?: string },
+    ) => WorkflowCodeVaultAsset
+}
+```
+
+Creates an inert declaration for a local file that should be available to `splitter()` or `crop()`. Source evaluation and offline compile do not read the file, upload it, or require credentials. `sync` resolves the path relative to `workflow-code.config.ts`, rejects paths outside that project directory, hashes the content, and uploads it before the first workflow lifecycle mutation. A matching content hash in the active context lock reuses the existing Vault ref.
+
+```ts
+const localInvoice = vault.asset('./fixtures/invoice.pdf', {
+    name: 'invoice.pdf',
+    mimeType: 'application/pdf',
+})
+
+const selectedPages = crop({
+    name: 'Crop local invoice',
+    input: {
+        file: localInvoice,
+        indexes: [1, '3-5'],
+    },
+})
+```
+
+`path`, `name`, and `mimeType` must be non-empty strings when present. Offline compile without a matching explicit asset snapshot reports `vault.asset.missing_lock`; it never falls back to reading the local file. If the file changes, the next `sync` uploads the new content and updates the lock.
+
 ### `vault.ref(reference)`
 
 ```ts
@@ -494,7 +573,7 @@ const existingPages = splitter({
 })
 ```
 
-During compile, a direct Vault ref used by `splitter.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
+During compile, a direct Vault ref used by `splitter.input.file` or `crop.input.file` lowers to a transport-file object containing both `fileUrl` and `vaultReference`. Compile remains offline. Before remote workflow mutation, sync and publish validate access to every compiled Vault ref in the active Tela context.
 
 ### `agent(remoteRef, options)`
 

package/dist/docs/workflow-code/manifest.json

@@ -14,7 +14,7 @@
       "slug": "api-reference",
       "title": "API Reference",
       "file": "api-reference.md",
-      "sha256": "2306f6a21d23b4e3457262c3105e65e0292af5a59154aa15cf24188409db07f8"
+      "sha256": "fc121fd8c0e83e4f39ecef45b50d4fc9b0bc64888bd10d0590b3ca168af0a42d"
     },
     {
       "slug": "cli",