> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Perceptions

> Describe a Pane’s native value and permitted Pane references with a TypeScript declaration.

## Sources

Docs: [Panes](/ponder/parables/pieces/panes), [Plots](/ponder/parables/pieces/plots), [Policies](/ponder/parables/pieces/policies), and [Preferences](/ponder/parables/pieces/preferences).

Web App: Select a Pane or Page and open **Perception** to compare its declaration with the read-only platform base.

## Schema

A Perception is a TypeScript `.d.ts` declaration exporting `Perception` and
conforming to `BasePerception`. It describes allowed values and references.
It does not select another actor's saved data.

```ts theme={null}
import type { BasePerception } from 'parable/foundation';
import type { Panes } from 'parable/panes';
import type { Temporal } from '@psgen/scalar-lib';

type Scenario = {
  name: string;
  startDate: Temporal.Date;
  departments: string[];
};

export interface Perception extends BasePerception<Scenario> {
  readonly panes: {
    categories: Panes['workCategories'];
  };
}
```

| Base field  | Meaning                                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------------------- |
| `primitive` | The native value type supplied through `BasePerception<T>`. Ordinary data fields belong inside this type. |
| `panes`     | Named, typed references to other Panes in this Parable.                                                   |
| `plots`     | Declared `PlotContract<Input, Output>` computations, bound by the host to owned Plot identities.          |
| `policies`  | Fixed resolved Policy decisions supplied by the host.                                                     |

All four fields are required. Extra root fields and index signatures are refused.
Declare Plots through `BasePerception<Primitive, DeclaredPlots>` or a structured
`plots` field. The resolved `policies` contract cannot be replaced or narrowed.
Objects, arrays, maps, unions, native types, and semantic scalars describe the
primitive without adding Property entities.

A Plot reference is not a Pane reference. SQL and React source use their
canonical value contracts without acquiring Pane composition. CSS is attached
by the renderer and is not a Palette configuration in the Perception declaration.
A Page is a placement Pane with `BasePerception<null>`.

Export interfaces and type aliases from a Perception to reuse them in another
Pane's React source. Use `import type` from the host declaration module
`parable/panes/<Pane ID>/perception`, using its stable Pane identity. Type-only
imports do not mount the target Pane or grant access to its Preferences or
runtime API. Runtime Pane imports still require a declared `panes` reference.

## Storage

The declaration is authored source. Saving checks it with the TypeScript
compiler and derives value validation and reference bindings. Those derived
fields cannot be edited independently to bypass the declaration. A schema edit
must also keep existing live application values valid.

The editor presents readable handles. Stored references use stable identities,
so renaming a Pane does not redirect existing references to a new Pane that
later takes the old name.

## Security

Types describe what a value can contain; Policies decide which actions the
requester may perform. `BasePerception.policies` and React's `props.policies`
contain generated `ParableResolvedPolicies` decisions.
Read settings separately through `preferences.readPolicies` when permitted.

The host always supplies the required props. A component may ignore props it
does not use, but that does not remove the Pane's schema or access checks.
Private declarations are not required merely to render an allowed value;
representation metadata tells the renderer how to reconstruct native values.
Typed Preference requests carry a compiler-derived fingerprint of the selected
primitive contract. A changed imported constraint or native representation
requires the SDK to refresh; changing a Preference value does not change this
fingerprint. The fingerprint never grants permission.

## Stability

Invalid references, missing base fields, and attempts to replace the fixed
contract are refused. Repair the declaration before saving; a preview error does
not itself grant or remove source-inspection permission.

`Temporal.Date` is a validated calendar-day string. A native `Date` is restored
as a JavaScript Date, while branded `Temporal.DateTime` remains a string.
Native Date wire values require an explicit timezone and an instant representable
in milliseconds. More precise values are refused instead of being truncated.
SQL output canonicalizes native Dates to UTC, including Dates inside objects
and arrays. Branded timestamp strings retain their supported fractional precision.
`@psgen/scalar-lib` supplies the same scalar parsers used by the platform.

Private representation metadata omits literal constraints. If several matching
union branches would require different native representations, loading refuses
with an ambiguous-representation error rather than supplying the wrong value.
Use the same representation across those branches or separate Pane types for
that case today. An explicit `Date | string` may remain a string.

## Reference

Generated Workspace API reference for this Piece:

* [Edit a Piece in Personal mode](/protocols/reference/web-api/parable-authoring-save-workspace-parable-primary)
* [Edit a Piece in Publishing mode](/protocols/reference/web-api/parable-authoring-save-workspace-parable-proposal)
* [Read a Parable's contents](/protocols/reference/web-api/parable-authoring-workspace-parable-primary-package)