oportunidades 8
tests / ci (push) Canceled after 0s

This commit is contained in:
2026-10-14 08:25:30 +02:00
parent 287e991486
commit ba1c0340ea
9112 changed files with 2199795 additions and 856 deletions
@@ -0,0 +1,274 @@
# Presentation Quick Start (TypeScript)
## API Docs
API docs: `api/API_DOCS.md`
`Presentation` is the in-memory API object. A deck is the exported presentation
file. A slide is one page in the deck.
## Imports
```ts
import fs from "node:fs/promises";
import { FileBlob, Presentation, PresentationFile } from "@oai/artifact-tool";
```
## Create, Render, Export
This script creates an editable deck, renders each slide PNG, and exports PPTX.
```ts
import fs from "node:fs/promises";
import { Presentation, PresentationFile } from "@oai/artifact-tool";
async function writeBlob(path: string, blob: Blob): Promise<void> {
await fs.writeFile(path, new Uint8Array(await blob.arrayBuffer()));
}
async function main(): Promise<void> {
await fs.mkdir("output", { recursive: true });
const presentation = Presentation.create({
slideSize: { width: 1280, height: 720 },
});
const slide = presentation.slides.add();
slide.background.fill = "slate-50";
const page = { left: 72, top: 64, width: 1136, height: 592 };
const gutter = 28;
const leftCol = 430;
const rightCol = page.width - leftCol - gutter;
const eyebrow = slide.shapes.add({
geometry: "textbox",
position: { left: page.left, top: page.top, width: 280, height: 28 },
fill: "none",
line: { style: "solid", fill: "none", width: 0 },
});
eyebrow.text = "EDITABLE PRESENTATION";
eyebrow.text.style = { fontSize: 12, bold: true, color: "slate-500" };
const title = slide.shapes.add({
geometry: "textbox",
position: {
left: page.left,
top: page.top + 92,
width: leftCol,
height: 184,
},
fill: "none",
line: { style: "solid", fill: "none", width: 0 },
});
title.text = "Build decks with editable objects";
title.text.style = { fontSize: 42, bold: true, color: "slate-950" };
const subtitle = slide.shapes.add({
geometry: "textbox",
position: {
left: page.left,
top: page.top + 292,
width: leftCol,
height: 96,
},
fill: "none",
line: { style: "solid", fill: "none", width: 0 },
});
subtitle.text =
"Rows, columns, grids, charts, tables, images, and text remain editable.";
subtitle.text.style = { fontSize: 20, color: "slate-600" };
const chartFrame = slide.shapes.add({
geometry: "roundRect",
name: "chart-frame",
position: {
left: page.left + leftCol + gutter,
top: page.top + 92,
width: rightCol,
height: 388,
},
fill: "white",
line: { style: "solid", fill: "slate-200", width: 1 },
borderRadius: "rounded-2xl",
shadow: "shadow-sm",
});
slide.charts.add("bar", {
position: {
left: chartFrame.position.left + 36,
top: chartFrame.position.top + 52,
width: chartFrame.position.width - 72,
height: 280,
},
categories: ["Rows", "Grid", "Tokens"],
series: [{ name: "Coverage", values: [3, 4, 5], fill: "accent1" }],
hasLegend: false,
dataLabels: { showValue: true, position: "outEnd" },
yAxis: {
majorGridlines: { style: "solid", fill: "slate-200", width: 1 },
},
});
for (const [index, slide] of presentation.slides.items.entries()) {
const stem = `slide-${String(index + 1).padStart(2, "0")}`;
const png = await presentation.export({ slide, format: "png", scale: 1 });
await writeBlob(`output/${stem}.png`, png);
}
const pptx = await PresentationFile.exportPptx(presentation);
await pptx.save("output/deck.pptx");
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});
```
Inspect every final slide at full size before delivery. After repairs, refresh
the affected slide previews, including slides affected by inherited changes.
Add the [optional inspection exports](#optional-inspection-exports) when needed.
## JSX Compose Equivalent
Use JSX when the slide is naturally rows, columns, grids, or overlays.
```tsx
/** @jsxRuntime automatic */
/** @jsxImportSource @oai/artifact-tool/presentation-jsx */
const frame = { left: 72, top: 64, width: 1136, height: 592 };
slide.compose(
<column name="content-frame" width="fill" height="fill" gap={28}>
<row width="fill" height={72} align="center" justify="between">
<paragraph name="eyebrow" className="text-slate-500 text-sm font-bold">
EDITABLE PRESENTATION
</paragraph>
<paragraph className="text-slate-400 text-sm">Q2 planning</paragraph>
</row>
<row width="fill" height="fill" gap={28} align="stretch">
<column width={430} height="fill" gap={18}>
<paragraph
name="primary-heading"
className="text-slate-950 text-5xl font-bold leading-tight"
>
Build decks with editable objects
</paragraph>
<paragraph className="text-slate-600 text-xl leading-relaxed">
Rows, columns, grids, charts, tables, images, and text remain
editable.
</paragraph>
</column>
<box
name="chart-frame"
width="fill"
height="fill"
className="bg-white rounded-2xl shadow-sm"
line={{ style: "solid", fill: "slate-200", width: 1 }}
>
<chart
name="coverage-chart"
chartType="bar"
categories={["Rows", "Grid", "Tokens"]}
series={[{ name: "Coverage", values: [3, 4, 5], fill: "accent1" }]}
hasLegend={false}
width="fill"
height="fill"
/>
</box>
</row>
</column>,
{ frame, baseUnit: 8 },
);
```
## Import And Edit PPTX
Load a PPTX, inspect for stable ids, render the affected slide before and after
a focused edit, re-inspect, and export the edited PPTX.
```ts
const presentation = await PresentationFile.importPptx(
await FileBlob.load("input.pptx"),
);
const before = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
search: "Revenue",
maxChars: 8000,
});
console.log(before.ndjson);
const slide = presentation.resolve(slideIdFromInspect);
await writeBlob(
"output/before-slide.png",
await presentation.export({ slide, format: "png", scale: 1 }),
);
const target = presentation.resolve(anchorIdFromInspect);
target.text.replace("Revenue", "Updated revenue outlook");
await writeBlob(
"output/after-slide.png",
await presentation.export({ slide, format: "png", scale: 1 }),
);
const after = await presentation.inspect({
target: { id: anchorIdFromInspect, beforeLines: 2, afterLines: 2 },
kind: "textbox,shape,image,table,chart",
maxChars: 3000,
});
console.log(after.ndjson);
const pptx = await PresentationFile.exportPptx(presentation);
await pptx.save("output/edited-deck.pptx");
```
## Optional Inspection Exports
When investigating placement, export layout evidence for the affected slide
in the authoring process. Capture it before and after a change when comparison
is useful.
```ts
const layout = await slide.export({ format: "layout" });
await fs.writeFile("output/slide.layout.json", await layout.text());
```
For deck flow or changes affecting multiple slides, add an overview montage.
Continue to inspect individual slide PNGs at full size.
```ts
const montage = await presentation.export({
format: "webp",
montage: true,
});
await writeBlob("output/deck-montage.webp", montage);
```
## Local Image Bytes
Use byte-backed images for embedded PPTX assets.
```ts
async function readImageBlob(imagePath: string): Promise<ArrayBuffer> {
const bytes = await fs.readFile(imagePath);
return bytes.buffer.slice(
bytes.byteOffset,
bytes.byteOffset + bytes.byteLength,
);
}
const imageBytes = await readImageBlob("assets/product.png");
slide.images.add({
blob: imageBytes,
contentType: "image/png",
alt: "Product screenshot",
fit: "cover",
position: { left: 720, top: 96, width: 420, height: 280 },
geometry: "roundRect",
borderRadius: "rounded-xl",
});
```
@@ -0,0 +1,270 @@
# Presentation API Docs
Use the presentation facades to create PowerPoint-style decks in TypeScript.
## Conventions (units + presets)
- **Pixels everywhere**: all slide geometry uses CSS pixels (`px`) at 96 DPI: `position.{left,top,width,height}`, line widths, and text `fontSize`.
- **Default canvas for examples**: use `1280 x 720` unless the task or source deck says otherwise. A useful full-slide content frame is `{ left: 72, top: 64, width: 1136, height: 592 }`.
- **Angles**: rotations use degrees.
- **Preset geometry**: `geometry` uses preset shape-name strings. Use standard shape presets and `geometry: "custom"` for bespoke paths.
- **Gradients**: stop `offset` ranges from `0` to `100000`.
- **Config-first authoring**: pass config objects into create/add APIs and grouped setters when the API provides them.
- **String values**: options such as geometry, fit, alignment, chart type, line style, and connector kind are strings; reference pages list exact small unions and grep targets for huge catalogs.
- **Inline docs types**: reference pages include illustrative `type ... = { ... }` blocks. Treat them as schema-shaped authoring guidance, not imports.
- **Authoring surfaces**: `slide.compose(...)` covers rows, columns, grids, layers, and token strings. Config-first facade APIs cover exact positions, fixed chrome, native charts/tables/images, and imported deck edits.
## Common Routes
- Rows, columns, grids, overlays, and 12-column spans: [`references/cookbook/layout.md`](./references/cookbook/layout.md).
- JSX node props and sizing mechanics: [`references/jsx.md`](./references/jsx.md).
- Tailwind-like visual strings: [`references/tokens.md`](./references/tokens.md).
- Inspect, resolve, edit, preview, and re-inspect loops: [`references/cookbook/imported-deck.md`](./references/cookbook/imported-deck.md).
## Quick start
```ts
const presentation = Presentation.create({
slideSize: { width: 1280, height: 720 },
});
const slide = presentation.slides.add();
slide.background.fill = "slate-50";
const headline = slide.shapes.add({
geometry: "textbox",
name: "headline",
position: { left: 72, top: 64, width: 720, height: 96 },
fill: "none",
line: { style: "solid", fill: "none", width: 0 },
});
headline.text = "Editable headline";
headline.text.style = { fontSize: 44, bold: true, color: "slate-950" };
const shape = slide.shapes.add({
geometry: "roundRect",
name: "summary-surface",
position: { left: 72, top: 188, width: 520, height: 300 },
fill: "white",
line: { style: "solid", fill: "slate-200", width: 1 },
borderRadius: "rounded-2xl",
});
const previewBlob = await presentation.export({
slide,
format: "png",
scale: 2,
});
const deckPdfBlob = await presentation.export({ format: "pdf" });
const slidePdfBlob = await presentation.export({ slide, format: "pdf" });
const snapshot = await presentation.inspect({
kind: "slide,textbox,shape",
maxChars: 4000,
});
const help = presentation.help("*", {
search: "chart axis labels",
include: ["index", "notes"],
maxChars: 4000,
});
const proto = presentation.toProto();
```
Inspect every final slide PNG at full size. After repairs, refresh previews for
the affected slides, including those affected by inherited changes.
## Optional Inspection Exports
When investigating placement, export layout evidence for the affected slide:
```ts
const layoutBlob = await slide.export({ format: "layout" });
```
For deck flow or changes affecting multiple slides, export an overview montage:
```ts
const montageBlob = await presentation.export({
format: "webp",
montage: true,
});
```
Capture these before and after edits when comparison is useful. A montage
supports deck-level review; use individual PNGs for full-size slide inspection.
## Load Existing Presentation Data
Load a PPTX from a local path:
```ts
const presentation = await Presentation.load("input.pptx");
```
Load serialized presentation data with `Presentation.load(proto)`:
```ts
const presentation = Presentation.load(proto);
const before = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
search: "Revenue",
maxChars: 8000,
});
const slide = presentation.resolve(slideAnchorIdFromInspect);
const previewBefore = await presentation.export({
slide,
format: "png",
scale: 1,
});
const target = presentation.resolve(anchorIdFromInspect);
target.text.replace("Revenue", "Revenue outlook");
target.text.style = { fontSize: 24, color: "slate-950", bold: true };
const previewAfter = await presentation.export({
slide,
format: "png",
scale: 1,
});
const after = await presentation.inspect({
target: { id: anchorIdFromInspect, beforeLines: 2, afterLines: 2 },
kind: "textbox,shape,image,table,chart",
maxChars: 3000,
});
const nextProto = presentation.toProto();
```
## Compose-first layout
```tsx
/** @jsxRuntime automatic */
const presentation = Presentation.create();
const slide = presentation.slides.add();
slide.compose(
<column width="fill" height="fill" gap={16}>
<paragraph
name="headline"
className="text-slate-950 text-3xl leading-tight"
>
<run textStyle={{ bold: true }}>Quarterly</run>
<run> readiness</run>
</paragraph>
<rule stroke="#0f172a" width={160} weight={2} />
</column>,
{
frame: { left: 48, top: 40, width: 864, height: 460 },
baseUnit: 8,
},
);
```
Use `name` for stable inspect and layout-export targeting. JSX materializing
tags default `width` to `"fill"` when you omit it.
## Core API Sequence
- Create presentations with `Presentation.create({ slideSize })` to control default slide dimensions.
- Add slides with `presentation.slides.add({ layout, layoutId })` or `presentation.slides.insert({ after, ... })`.
- Use `slide.compose(nodeOrJsx, { frame, baseUnit })` for compose-first layouts. JSX lowers into the same compose runtime as the helper-based API.
- Author content with config-first calls: `slide.shapes.add({ geometry, position, fill, line })`, `slide.images.add({ ... })`, `slide.tables.add({ ... })`, and `slide.charts.add(chartType, { ... })`.
- Format whole-shape text with grouped configs such as `shape.text.style = { fontSize, bold, color, alignment }`.
- Edit imported decks with `presentation.inspect({ kind, search, maxChars })`, `presentation.resolve(anchorId)`, and focused facade edits.
- Export previews with `presentation.export({ slide, format, scale })`.
- Export all slides as one PDF with `presentation.export({ format: "pdf" })`.
- Export deck montages for overview review with `presentation.export({ format: "webp", montage: true })`.
- Export layout JSON for placement investigations with `slide.export({ format: "layout" })`.
- Control editor gridlines and imported guides with `presentation.view`.
- Search API help with `presentation.help(query, { search, include, maxChars })`.
- Run high-level edits with `presentation.scripts.run(kind, options)`; see [`references/presentation.spec.md`](./references/presentation.spec.md) for the script surface.
## Output Map
| Output | API | Result |
| ------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------ |
| All slide previews | `presentation.render()` | PNG blobs in deck order, named `slide-1.png`, `slide-2.png`, and so on |
| Selected previews | `presentation.render({ slide: [0, 2] })` | PNG blobs for zero-based indexes, in requested order |
| Raster preview | `presentation.render({ slide, format: "png", scale })` | One raster blob for a `Slide` or a single zero-based index |
| Slide PNG | `presentation.export({ slide, format: "png", scale })` | One preview image for one slide |
| Deck PDF | `presentation.export({ format: "pdf" })` | One PDF `Blob` with one page per slide |
| Slide PDF | `presentation.export({ slide, format: "pdf" })` | One PDF `Blob` for one slide |
| Editable PPTX | `presentation.export({ format: "pptx" })` | Editable presentation `Blob` |
| Deck montage | `presentation.export({ format: "webp", montage: true, scale })` | One overview image containing the deck slides |
| Layout JSON | `slide.export({ format: "layout" })` | Structural JSON with bounds, ids, text, names, and object metadata |
| Searchable snapshot | `presentation.inspect({ kind, search, maxChars })` | NDJSON records for locating and resolving objects |
| Runtime handoff | `presentation.toProto()` | Serializable presentation data for host adapters |
## Minimal Patterns
Use these as the first API patterns to reach for:
```ts
// Create, preview, inspect, then serialize.
const presentation = Presentation.create({
slideSize: { width: 1280, height: 720 },
});
const slide = presentation.slides.add();
const preview = await presentation.export({ slide, format: "png", scale: 1 });
const snapshot = await presentation.inspect({
kind: "slide,textbox,shape,image,chart,table",
maxChars: 4000,
});
const proto = presentation.toProto();
```
```tsx
// Compose structure with first-principles rows/columns.
slide.compose(
<row width="fill" height="fill" gap={28}>
<column width={420} height="fill" gap={16}>
<paragraph className="text-slate-950 text-5xl font-bold leading-tight">
Title
</paragraph>
<paragraph className="text-slate-600 text-xl leading-relaxed">
Editable copy in a fixed text column.
</paragraph>
</column>
<box
width="fill"
height="fill"
className="bg-slate-50 rounded-2xl shadow-sm"
/>
</row>,
{ frame: { left: 56, top: 56, width: 1168, height: 608 }, baseUnit: 8 },
);
```
For 3-column and 12-column layouts, use [`references/cookbook/layout.md`](./references/cookbook/layout.md); keep spans local with `{ mode: "fr", value: 1 }` track objects.
Use `className` only for visual/text tokens such as `bg-*`, `rounded-*`,
`shadow-*`, `text-*`, `font-*`, and `leading-*`. Use layout props for
`width`, `height`, `gap`, `padding`, `align`, and `justify`.
## Reference Map
Open these references as needed:
- [`references/jsx.md`](./references/jsx.md) — compact JSX node surface and layout mechanics.
- [`references/tokens.md`](./references/tokens.md) — Tailwind-like token reference for colors, text, radius, shadows, and `className`.
- [`references/cookbook/layout.md`](./references/cookbook/layout.md) — first-principles layout recipes for rows, columns, 12-column grids, alignment, masks, and overlays.
- [`references/cookbook/imported-deck.md`](./references/cookbook/imported-deck.md) — safe inspect, resolve, edit, preview, and re-inspect loops for existing decks.
- [`references/presentation.spec.md`](./references/presentation.spec.md) — `Presentation` facade, slide collection, view controls, export/toProto, scripts.
- [`references/slide.spec.md`](./references/slide.spec.md) — `Slide` API, backgrounds, placeholders, notes, export, auto-layout.
- [`references/inspect.md`](./references/inspect.md) — grep-first snapshot (`inspect → rg → resolve/edit → re-inspect`) for loaded presentation data and templates.
- [`references/help.md`](./references/help.md) — grep-first API and template lookup (`help → build/edit → inspect`) for presentation JS workflows.
- [`references/layout.spec.md`](./references/layout.spec.md) — layouts, placeholders, and slide layout assignment.
- [`references/master.spec.md`](./references/master.spec.md) — masters, layout linking, background refs, color maps.
- [`references/theme.spec.md`](./references/theme.spec.md) — theme color schemes and hex maps.
- [`references/styles.spec.md`](./references/styles.spec.md) — named text styles and flow through text.
- [`references/rich-text.spec.md`](./references/rich-text.spec.md) — text blocks, ranges, links, list presets.
- [`references/shapes.spec.md`](./references/shapes.spec.md) — shape geometry, custom Bézier curves, fills, strokes, rounded corners, shadows, and z-ordering.
- [`references/connectors.md`](./references/connectors.md) — connected lines, arrows, side anchors, direct connection sites, and rerouting behavior.
- [`references/fill.spec.md`](./references/fill.spec.md) — fill/stroke config shapes and color shorthands, solid, gradient, pattern.
- [`references/images.spec.md`](./references/images.spec.md) — images, cropping, contain/cover framing, prompt placeholders.
- [`references/tables.spec.md`](./references/tables.spec.md) — tables, merges, and cell text.
- [`references/charts.spec.md`](./references/charts.spec.md) — charts, series, axes, legends, mini-chart YAML.
- [`references/comments.md`](./references/comments.md) — comment authors, threads, replies, reactions, and resolving imported review threads.
- [`references/auto-layout.spec.md`](./references/auto-layout.spec.md) — deterministic layout helpers for arranging shapes within frames.
- [`references/speaker-notes.spec.md`](./references/speaker-notes.spec.md) — speaker notes surface and visibility toggles.
@@ -0,0 +1,100 @@
# Auto Layout
`slide.autoLayout(...)` places shapes within a frame using deterministic spacing.
Use `slide.compose(<row>/<column>/<grid>)` for new structured JSX layouts. Use
`slide.autoLayout(...)` when repositioning existing facade shapes, especially
imported or generated shapes.
## Pattern
```ts
slide.autoLayout(shapes, {
direction,
frame,
align,
horizontalGap,
verticalGap,
horizontalPadding,
verticalPadding,
});
```
## Inputs
- `direction`: horizontal or vertical flow.
- `frame`: `"slide"`, container `Shape`, or explicit `{ left, top, width, height }`.
- `align`: 3x3 group alignment within the frame.
- Gap and padding values use pixels.
## Inline Types
```ts
type AutoLayoutOptions = {
direction?: "horizontal" | "vertical";
frame?:
| "slide"
| Shape
| { left: number; top: number; width: number; height: number };
align?:
| "center"
| "topLeft"
| "topCenter"
| "topRight"
| "left"
| "right"
| "bottomLeft"
| "bottomCenter"
| "bottomRight";
horizontalGap?: number | "auto";
verticalGap?: number | "auto";
horizontalPadding?: number;
verticalPadding?: number;
};
```
## Shape Prep
```ts
for (const shape of shapes) {
shape.position = {
width: shapeWidthPx,
height: shapeHeightPx,
};
}
slide.autoLayout(shapes, layoutConfig);
```
## Cookbook
```ts
// Equal KPI row.
const kpiShapes = metrics.map((metric) =>
slide.shapes.add({
geometry: "roundRect",
position: { width: 240, height: 132 },
fill: "white",
line: { style: "solid", fill: "slate-200", width: 1 },
borderRadius: "rounded-xl",
}),
);
slide.autoLayout(kpiShapes, {
direction: "horizontal",
frame: { left: 80, top: 160, width: 1120, height: 160 },
horizontalGap: "auto",
align: "center",
});
```
```ts
// Vertical callout stack inside an existing shape frame.
slide.autoLayout(callouts, {
direction: "vertical",
frame: frameShape,
verticalGap: 14,
horizontalPadding: 24,
verticalPadding: 24,
align: "topLeft",
});
```
@@ -0,0 +1,330 @@
# Charts
`slide.charts` creates chart elements with slide placement and chart configuration.
## Resolved From Inspect
```ts
const chart = presentation.resolve("ch/b2c3d4e5");
chart.title = "Updated chart title";
chart.yAxis = { numberFormatCode: "$#,##0M" };
chart.series.getItemAt(0).values = [3.1, 3.7, 4.2, 4.8];
```
Use `presentation.inspect({ kind: "chart", search })` to find the `ch/...`
anchor id. If an imported chart resolves as an image, preserve it as an image or
rebuild it as a native chart intentionally.
## Add Chart
```ts
const chart = slide.charts.add(chartType, {
position,
title,
titleTextStyle,
categories,
series,
hasLegend,
legend,
barOptions,
lineOptions,
areaOptions,
pieOptions,
doughnutOptions,
treemapOptions,
mapOptions,
funnelOptions,
boxWhiskerOptions,
histogramOptions,
view3d,
scatterOptions,
radarOptions,
bubbleOptions,
xAxis,
yAxis,
dataLabels,
dataTable,
chartFill,
chartLine,
plotAreaFill,
plotAreaLine,
});
```
Small chart option enums are listed below.
## Chart Inline Types
```ts
type ChartTypeName =
| "line" | "pie" | "bar" | "doughnut" | "scatter" | "bubble" | "radar"
| "treemap" | "sunburst" | "map" | "waterfall" | "line3D" | "pie3D"
| "area3D" | "bar3D" | "funnel" | "histogram" | "boxWhisker" | "stock"
| "surface3D" | "ofPie" | "surface" | "pareto" | "combo" | "area";
type ChartConfig = {
position?: { left?: number; top?: number; width?: number; height?: number };
title?: string;
roundedCorners?: boolean | null;
titlePlacement?: "none" | "aboveChart" | "centeredOverlay";
titleTextStyle?: ChartTextStyleConfig;
categories?: string[];
series?: ChartSeriesConfig[];
hasLegend?: boolean;
legend?: ChartLegendConfig;
barOptions?: { direction?: "bar" | "column"; grouping?: "clustered" | "stacked" | "percentStacked"; varyColors?: boolean; gapWidth?: number; gapDepth?: number; overlap?: number; bar3dShape?: number };
lineOptions?: { grouping?: "standard" | "stacked" | "percentStacked"; smooth?: boolean; varyColors?: boolean };
areaOptions?: { grouping?: "standard" | "stacked" | "percentStacked"; varyColors?: boolean };
pieOptions?: { firstSliceAngle?: number };
doughnutOptions?: { holeSize?: number; firstSliceAngle?: number };
treemapOptions?: { parentLabelLayout?: "none" | "overlapping" | "banner" };
mapOptions?: { mapArea?: "world" | "auto" | "dataOnly" | "region"; projection?: "mercator" | "auto" | "miller" | "albers"; labelLayout?: "none" | "bestFit" | "showAll"; dataLevel?: "auto" | "county" | "postalCode" | "countryOrRegion" | "stateOrProvince" | "stateCode" | "countyCode" | "countryOrRegionCode"; showUnknown?: boolean; onlyRegionsWithData?: boolean };
funnelOptions?: { gapWidth?: number };
boxWhiskerOptions?: { showMeanLine?: boolean; showMeanMarker?: boolean; showNonOutliers?: boolean; showOutliers?: boolean; quartileMethod?: "inclusive" | "exclusive" };
histogramOptions?: { binWidth?: number | null; binCount?: number | null; underflow?: number | null; overflow?: number | null; intervalClosed?: number; aggregated?: boolean };
view3d?: { rotX?: number; rotY?: number; perspective?: number; rightAngleAxes?: boolean };
scatterOptions?: { style?: "line" | "lineWithMarkers" | "marker" | "smooth" | "smoothWithMarkers"; varyColors?: boolean };
radarOptions?: { style?: "standard" | "marker" | "filled"; varyColors?: boolean };
bubbleOptions?: { scale?: number | null; sizeRepresents?: "area" | "width" | null; showNegative?: boolean | null };
xAxis?: ChartAxisConfig;
yAxis?: ChartAxisConfig;
dataLabels?: ChartDataLabelsConfig;
dataTable?: ChartDataTableConfig;
chartFill?: FillConfig;
chartLine?: LineConfig;
plotAreaFill?: FillConfig;
plotAreaLine?: LineConfig;
displayBlanksAs?: "zero" | "gap" | "span" | null;
styleIndex?: number;
};
```
## Chart Family Options
```ts
histogram.histogramOptions = { binWidth: 5 };
histogram.histogramOptions = { binCount: 8, underflow: 0, overflow: 30 };
histogram.histogramOptions = { binWidth: null, binCount: null };
histogram.histogramOptions = { underflow: null, overflow: null };
bubble.bubbleOptions = { scale: 150, sizeRepresents: "area" };
bubble.bubbleOptions = { scale: null, sizeRepresents: null };
bubble.bubbleOptions = { showNegative: true };
```
## Grouped Edits
```ts
chart.xAxis = axisConfig;
chart.yAxis = axisConfig;
chart.legend = legendConfig;
chart.dataLabels = dataLabelsConfig;
chart.dataTable = dataTableConfig;
```
### Data Labels
```ts
chart.dataLabels = { showValue: true, position: "outEnd" };
chart.dataLabels = { textStyle: { fontSize: 14 } };
chart.dataLabels.showCategoryName = true;
const series = chart.series.getItemAt(seriesIndex);
series.dataLabels = { showValue: false, showSeriesName: true };
series.dataLabels.showSeriesName = false;
```
Config assignments update supplied fields and preserve omitted values. New label
collections initialize all seven `show*` flags to `false`. A series without its
own label collection inherits chart labels; omitted point flags inherit series
or chart labels.
### Axis Placement
```ts
chart.xAxis = { crossesAt: 2 }; // The value axis crosses at category 2.
chart.yAxis = { crossesAt: 25 }; // The category axis crosses at value 25.
chart.yAxis = { tickLabelPosition: "high" };
```
## Series
```ts
const chart = slide.charts.add(chartType, {
categories,
series: [
{
name: seriesName,
categories,
values,
xValues,
categoryPaths,
fill: fillConfig,
line: lineConfig,
marker: markerConfig,
points,
dataLabels: dataLabelsConfig,
dataLabelOverrides,
trendlines,
errorBars,
},
],
});
```
## Series Inline Type
```ts
type ChartSeriesConfig = {
name: string;
categories?: string[];
values?: Array<number | null>;
xValues?: Array<number | null>;
categoryPaths?: string[][];
bubbleSizes?: Array<number | null>;
bubbleSizeFormula?: string;
bubbleSizesFormatCode?: string;
explosion?: number;
smooth?: boolean;
fill?: FillConfig;
line?: LineConfig;
stroke?: LineConfig;
// Scatter outline color defaults to the marker's solid fill; explicit stroke fills take precedence.
marker?: { symbol?: "circle" | "diamond" | "dot" | "none" | "plus" | "square" | "star" | "triangle" | "x"; size?: number; fill?: FillConfig };
points?: Array<{ idx: number; fill?: FillConfig; line?: LineConfig; stroke?: LineConfig }>;
dataLabels?: ChartDataLabelsConfig;
dataLabelOverrides?: Array<{ idx: number; text?: string; separator?: string; position?: string; fill?: FillConfig; line?: LineConfig; stroke?: LineConfig; showValue?: boolean; showSeriesName?: boolean; showCategoryName?: boolean; showPercent?: boolean; textStyle?: ChartTextStyleConfig }>;
trendlines?: Array<{
type?: "linear" | "exponential" | "logarithmic" | "polynomial" | "power" | "movingAverage";
name?: string;
polynomialOrder?: number;
movingAveragePeriod?: number;
forecastForward?: number;
forecastBackward?: number;
intercept?: number;
displayEquation?: boolean;
displayRSquared?: boolean;
line?: LineConfig;
label?: { text?: string; textStyle?: ChartTextStyleConfig; fill?: FillConfig; line?: LineConfig };
}>;
errorBars?: { type?: "standardError" | "percentage" | "standardDeviation" | "none"; value?: number; endStyle?: "cap" | "noCap"; line?: LineConfig };
valuesFormatCode?: string;
xValuesFormatCode?: string;
};
```
## Data Label Overrides
```ts
const override = chart.series
.getItemAt(seriesIndex)
.dataLabelOverrides.add(dataPointIdx);
override.text = labelText;
override.position = labelPosition;
override.textStyle.fontSize = fontSizePx;
override.textStyle.fill = textFill;
override.fill = fillConfig;
override.stroke = lineConfig;
```
## Chart Areas
```ts
const chart = slide.charts.add(chartType, {
chartFill,
plotAreaFill,
});
```
## Axis, Legend, Label Inline Types
```ts
type ChartTextStyleConfig = {
fontSize?: number;
fill?: FillConfig;
bold?: boolean;
italic?: boolean;
underline?: string;
alignment?: "left" | "center" | "right" | "justify";
};
type ChartLegendConfig = {
position?: "left" | "top" | "topRight" | "right" | "bottom";
overlay?: boolean;
fill?: FillConfig;
line?: LineConfig;
textStyle?: ChartTextStyleConfig;
};
type ChartDataLabelsConfig = {
visible?: boolean;
deleted?: boolean;
position?: "center" | "inEnd" | "outEnd" | "left" | "right" | "top" | "bottom" | "insideBase" | "bestFit" | "dataCallout";
showValue?: boolean;
showSeriesName?: boolean;
showCategoryName?: boolean;
showLegendKey?: boolean;
showPercent?: boolean;
showBubbleSize?: boolean;
showLeaderLines?: boolean;
numberFormatCode?: string;
numberFormatSourceLinked?: boolean;
separator?: string;
textStyle?: ChartTextStyleConfig;
fill?: FillConfig;
line?: LineConfig;
};
type ChartAxisConfig = {
visible?: boolean;
title?: string | { text?: string; textStyle?: ChartTextStyleConfig };
numberFormatCode?: string;
min?: number;
max?: number;
majorUnit?: number;
minorUnit?: number;
position?: "bottom" | "left" | "right" | "top";
tickLabelPosition?: "nextTo" | "high" | "low" | "none" | string;
labelOffsetPercent?: number; // Category-axis font-size percentage; 0–1000, default 100.
textStyle?: ChartTextStyleConfig;
line?: LineConfig;
majorGridlines?: LineConfig | null;
minorGridlines?: LineConfig | null;
};
```
## Cookbook
```ts
// Executive horizontal bar chart.
slide.charts.add("bar", {
position: { left: 96, top: 160, width: 720, height: 360 },
categories: ["Enterprise", "Mid-market", "SMB"],
series: [{ name: "ARR", values: [42, 28, 17], fill: "#2563eb" }],
barOptions: { direction: "bar", grouping: "clustered", gapWidth: 44 },
hasLegend: false,
xAxis: { visible: false, majorGridlines: null },
yAxis: { textStyle: { fill: "#475569", fontSize: 13 }, line: { style: "solid", fill: "#e2e8f0", width: 1 } },
dataLabels: { showValue: true, position: "outEnd", textStyle: { fill: "#0f172a", fontSize: 13, bold: true } },
});
```
```ts
// Compact trend line with muted grid.
slide.charts.add("line", {
position: { left: 96, top: 150, width: 880, height: 280 },
categories: ["Jan", "Feb", "Mar", "Apr"],
series: [{ name: "Conversion", values: [31, 34, 37, 43], line: { style: "solid", fill: "#0f766e", width: 3 } }],
legend: { position: "bottom", overlay: false },
yAxis: { numberFormatCode: "0%", majorGridlines: { style: "solid", fill: "#e2e8f0", width: 1 } },
});
```
```ts
// Doughnut chart with labels outside.
slide.charts.add("doughnut", {
categories: ["Product", "Sales", "Support"],
series: [{ name: "Share", values: [52, 31, 17] }],
dataLabels: { showPercent: true, showCategoryName: true, position: "outEnd" },
legend: { position: "right" },
});
```
@@ -0,0 +1,103 @@
# Comments
Presentation comments use people, threads, replies, reactions, and thread state.
## Current Author
```ts
presentation.comments.setSelf({
displayName,
initials,
email,
});
```
## Person Inline Type
```ts
type PersonConfig = {
id?: string;
displayName: string;
initials?: string;
email?: string;
avatarUrl?: string;
userId?: string;
providerId?: string;
};
```
## Element Thread
```ts
const thread = presentation.comments.addThread({ element }, bodyText, {
position,
});
const reply = thread.addReply(replyText);
reply.toggleReaction(reactionText);
thread.resolve();
thread.reopen();
```
## Thread Inline Types
```ts
type CommentTarget =
| { slide: Slide }
| { element: Shape | ImageElement | Table | ChartElement }
| { textRange: TextRange }
| { textMatch: { element: Shape; query: string; occurrence?: number } };
type ThreadAddOptions = {
author?: Person | PersonConfig | { id: string };
createdAt?: string;
position?: { x: number; y: number; unit?: "px" | "emu" };
};
```
## Slide And Text Threads
```ts
presentation.comments.addThread({ slide }, bodyText, { position });
presentation.comments.addThread(
{ textMatch: { element, query, occurrence } },
bodyText,
);
```
## Cookbook
```ts
// Add a review comment to exact text.
presentation.comments.setSelf({
displayName: "Presentation Reviewer",
initials: "PR",
email: "reviewer@example.com",
});
const thread = presentation.comments.addThread(
{ textMatch: { element: titleShape, query: "Q4", occurrence: 0 } },
"Check whether this should be FY2026 Q1.",
);
thread.addReply("Leaving this unresolved for owner review.");
```
```ts
// Resolve an imported thread after an edit.
const self = presentation.comments.setSelf({
displayName: "Presentation Editor",
initials: "PE",
email: "editor@example.com",
});
const thread = presentation.resolve(threadAnchorId);
thread.addReply("Updated the chart title and source note.", { author: self });
thread.resolve(self);
const verified = await presentation.inspect({
kind: "thread",
target: { id: threadAnchorId, beforeLines: 0, afterLines: 2 },
maxChars: 2000,
});
```
@@ -0,0 +1,225 @@
# Connectors
`slide.shapes.connect` creates connector lines that stay attached to slide
shapes. Use it for arrows, flow links, callouts, dependency lines, and other
relationships between positioned shapes.
Use direct `geometry: "connector"` creation only when you need exact connection
site indexes.
## Connect Shapes
```ts
const connector = slide.shapes.connect(sourceShape, targetShape, {
kind: "elbow",
fromSide: "right",
toSide: "left",
line: { style: "solid", fill: "slate-500", width: 2 },
head: { type: "arrow", width: "med", length: "med" },
});
```
Endpoints accept shape facades or shape ids. `fromSide` and `toSide` accept
`"top"`, `"left"`, `"bottom"`, or `"right"` and resolve to the nearest
connection site for that shape geometry. When you omit side and index options,
the API chooses a connection pair from the relative shape positions.
`kind` defaults to `"elbow"` for `slide.shapes.connect(...)`.
## Connect Inline Types
```ts
type ConnectorSide = "top" | "left" | "bottom" | "right";
type ShapeConnectOptions = {
kind?:
| "straight"
| "elbow"
| "elbow2"
| "elbow3"
| "elbow4"
| "elbow5"
| "curved";
fromSide?: ConnectorSide;
toSide?: ConnectorSide;
fromIdx?: number;
toIdx?: number;
line?: LineConfig;
head?: LineEndConfig;
tail?: LineEndConfig;
cap?: "flat" | "round" | "square";
join?: "round" | "bevel" | "miter";
};
type LineEndConfig = {
type?: "none" | "triangle" | "stealth" | "diamond" | "oval" | "arrow";
width?: "sm" | "med" | "lg";
length?: "sm" | "med" | "lg";
};
```
## Anchor Choice
Use side anchors for readable authoring:
```ts
slide.shapes.connect(sourceShape, targetShape, {
fromSide: "bottom",
toSide: "top",
kind: "elbow",
line: { style: "dashed", fill: "accent1", width: 2 },
});
```
Use explicit connection site indexes when you need an exact preset-geometry site:
```ts
const fromIdx = slide.shapes.getConnectionSiteIndex(sourceShape, "right");
const toIdx = slide.shapes.getConnectionSiteIndex(targetShape, "left");
slide.shapes.connect(sourceShape.id, targetShape.id, {
fromIdx,
toIdx,
kind: "straight",
line: { style: "solid", fill: "slate-700", width: 2 },
});
```
Connection site indexes are PowerPoint preset geometry connection points. Side
anchors map to the closest useful preset site for rectangles, ellipses, and
other shapes.
## Direct Connector Shape
```ts
const connector = slide.shapes.add({
geometry: "connector",
kind: "curved",
from: sourceShape,
fromIdx: 3,
to: targetShape,
toIdx: 1,
line: { style: "solid", fill: "accent1", width: 2 },
tail: { type: "triangle", width: "med", length: "med" },
});
```
## Unattached Connector
```ts
const arrow = slide.shapes.add({
geometry: "connector",
kind: "straight",
position: { left: 40, top: 160, width: 240, height: 0 },
line: { fill: "accent1", width: 2 },
tail: { type: "arrow" },
});
```
## One Attached Endpoint
```ts
const connector = slide.shapes.add({
geometry: "connector",
kind: "straight",
from: sourceShape,
fromIdx: slide.shapes.getConnectionSiteIndex(sourceShape, "right"),
position: { left: 40, top: 160, width: 240, height: 0 },
line: { fill: "accent1", width: 2 },
tail: { type: "arrow" },
});
```
## Direct Connector Inline Type
```ts
type ConnectorConfig = {
geometry: "connector";
from?: Shape | string;
fromIdx?: number;
to?: Shape | string;
toIdx?: number;
position?: PositionConfig;
kind?:
| "straight"
| "elbow"
| "elbow2"
| "elbow3"
| "elbow4"
| "elbow5"
| "curved";
line?: LineConfig;
head?: LineEndConfig;
tail?: LineEndConfig;
cap?: "flat" | "round" | "square";
join?: "round" | "bevel" | "miter";
};
```
Connectors support line styling and line ends, but not `borderRadius` or
`shadow`.
## Edit Existing Connectors
```ts
const connector = presentation.resolve(connectorAnchorId);
const nextFromIdx = slide.shapes.getConnectionSiteIndex(
nextSourceShape,
"right",
);
const nextToIdx = slide.shapes.getConnectionSiteIndex(nextTargetShape, "left");
connector.setConnectorFrom(nextSourceShape, nextFromIdx);
connector.setConnectorTo(nextTargetShape.id, nextToIdx);
connector.line = { style: "solid", fill: "slate-800", width: 2 };
connector.bringToFront();
```
Use `presentation.inspect({ kind: "shape", search })` to find connector anchor
ids. Connector facades expose `connector`, `connectorLineStyle`,
`connectorHead`, and `connectorTail` for readback.
## Routing And Ordering
New connectors are sent behind shapes by default so boxes and labels remain
readable. Call `connector.bringToFront()` when the connector should sit above
other elements.
## Cookbook
```ts
// Arrow from one card to another.
slide.shapes.connect(sourceCard, targetCard, {
kind: "elbow",
fromSide: "right",
toSide: "left",
line: { style: "solid", fill: "slate-500", width: 2 },
head: { type: "arrow", width: "med", length: "med" },
});
```
```ts
// Bidirectional relationship line.
slide.shapes.connect(leftShape, rightShape, {
kind: "straight",
fromSide: "right",
toSide: "left",
line: { style: "dashed", fill: "accent2", width: 2 },
head: { type: "arrow", width: "sm", length: "sm" },
tail: { type: "arrow", width: "sm", length: "sm" },
});
```
```ts
// Curved connector with explicit preset connection sites.
slide.shapes.add({
geometry: "connector",
kind: "curved",
from: sourceShape,
fromIdx: slide.shapes.getConnectionSiteIndex(sourceShape, "bottom"),
to: targetShape,
toIdx: slide.shapes.getConnectionSiteIndex(targetShape, "top"),
line: { style: "solid", fill: "accent1", width: 2 },
tail: { type: "triangle", width: "med", length: "med" },
});
```
@@ -0,0 +1,187 @@
# Imported Deck Cookbook
Use these recipes when editing an existing presentation. The goal is targeted,
type-aware edits with a preview and a small verification snapshot.
For imported decks, render the affected slide before and after focused edits,
export layout JSON before and after when object placement matters, and use a
deck montage before/after when a change may affect multiple slides.
## Load A PPTX
```ts
const presentation = await Presentation.load("input.pptx");
```
## Edit Loop
```ts
const before = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
search: "Revenue",
maxChars: 8000,
});
// Pick an exact anchor id from `before`; use inspect ids instead of slide indexes.
const target = presentation.resolve(anchorId);
// slideAnchorId is the `sl/...` id from inspect for the affected slide.
const slide = presentation.resolve(slideAnchorId);
const previewBefore = await slide.export({ format: "png", scale: 2 });
const layoutBefore = await slide.export({ format: "layout" });
const montageBefore = await presentation.export({
format: "webp",
montage: true,
scale: 1,
});
target.text.replace("Revenue", "Revenue outlook");
const previewAfter = await slide.export({ format: "png", scale: 2 });
const layoutAfter = await slide.export({ format: "layout" });
const montageAfter = await presentation.export({
format: "webp",
montage: true,
scale: 1,
});
const after = await presentation.inspect({
target: { id: anchorId, beforeLines: 2, afterLines: 2 },
kind: "textbox,shape",
maxChars: 2000,
});
```
## Placeholder Edit
```ts
const layoutSnapshot = await presentation.inspect({
kind: "slide,layout,textbox,shape",
search: "Click to add title",
maxChars: 6000,
});
// slideAnchorId is the `sl/...` id from inspect for this slide.
const slide = presentation.resolve(slideAnchorId);
const title = slide.placeholders.getItem("title");
title.text = "Updated executive summary";
```
Edit a slide placeholder for a local content change. Edit a layout or master
only when the intended change is global.
Inspect records use 1-based `slide` numbers for display; `slides.getItem(index)`
is 0-based. Prefer resolving the `sl/...` anchor from inspect.
## Master/Layout Blast Radius
```ts
// layoutId comes from inspect/layout export metadata; use it for search and comparison.
const affected = await presentation.inspect({
kind: "slide,layout",
search: layoutId,
maxChars: 6000,
});
```
Inspect affected layouts and slides before changing a master, layout, theme
color, or placeholder geometry. Use layout ids for comparison/search, then
resolve affected slides through their `sl/...` ids before editing. These edits
can update many slides.
## Preserve Imported Image Placement
```ts
const image = presentation.resolve(imageAnchorId);
const oldFrame = image.frame;
const oldCrop = image.crop;
const oldFit = image.fit;
const oldAlt = image.alt;
const oldPrompt = image.prompt;
const oldGeometry = image.geometry;
const oldBorderRadius = image.borderRadius;
const oldRotation = image.rotation;
const oldFlipHorizontal = image.flipHorizontal;
const oldFlipVertical = image.flipVertical;
const oldLockAspectRatio = image.lockAspectRatio;
image.replace({
blob: replacementBytes,
contentType: "image/png",
alt: oldAlt ?? "Updated product screenshot",
...(oldFit ? { fit: oldFit } : {}),
...(oldPrompt ? { prompt: oldPrompt } : {}),
});
image.frame = oldFrame;
image.crop = oldCrop;
image.geometry = oldGeometry;
image.borderRadius = oldBorderRadius;
image.rotation = oldRotation;
image.flipHorizontal = oldFlipHorizontal;
image.flipVertical = oldFlipVertical;
image.lockAspectRatio = oldLockAspectRatio;
```
Render the slide after replacement and verify subject crop, aspect ratio,
rounded mask, and legibility. Preserve placement-affecting properties unless the
edit explicitly changes them. Concrete source replacements produce concrete
images; pass `prompt` when it should remain available as regeneration metadata.
## Existing Table And Chart Edits
```ts
const table = presentation.resolve(tableAnchorId);
table.cells.set(1, 2, "$4.2M");
table.getCell(1, 2).text.style = "Body Small";
const chart = presentation.resolve(chartAnchorId);
chart.xAxis = { title: "Quarter" };
chart.yAxis = { numberFormatCode: "$#,##0M" };
chart.series.getItemAt(0).values = [3.1, 3.7, 4.2, 4.8];
await presentation.inspect({
kind: "table,chart",
target: { id: chartAnchorId, beforeLines: 3, afterLines: 3 },
maxChars: 3000,
});
```
If an imported chart or table resolves as an image, preserve it as an image or
rebuild it as a native chart/table intentionally.
## Comments And Speaker Notes
```ts
const review = await presentation.inspect({
kind: "thread,notes,slide,textbox",
search: "TODO",
maxChars: 8000,
});
const self = presentation.comments.setSelf({
displayName: "Presentation Editor",
initials: "PE",
email: "presentation@example.com",
});
const thread = presentation.resolve(commentThreadAnchorId);
thread.addReply("Addressed in this revision.", { author: self });
thread.resolve(self);
const notes = presentation.resolve(notesAnchorId);
const existing = notes.text.trim();
notes.text = [
existing,
"Opening: summarize the revised revenue outlook.",
"Call out risk on enterprise timing.",
].filter(Boolean).join("\n");
notes.setVisible(true);
const verified = await presentation.inspect({
kind: "thread,notes",
target: { id: slideAnchorId, beforeLines: 1, afterLines: 4 },
maxChars: 3000,
});
```
Keep unrelated threads and speaker notes intact unless the task explicitly asks
to clear them.
@@ -0,0 +1,419 @@
# Presentation Layout Cookbook
First-principles recipes for arranging editable presentation JSX. These are
layout mechanics, not deck archetypes.
Examples start after `presentation` and `slide` exist. Prefer string sizing
(`"fill"`, `"hug"`) and local track values over helper imports.
Use `1280 x 720` as the default canvas unless the task or source deck requires
another size:
```ts
const SLIDE_W = 1280;
const SLIDE_H = 720;
const PAGE = { left: 72, top: 64, width: 1136, height: 592 };
```
## Choose The Primitive
| Need | Use |
| --- | --- |
| Horizontal flow | `row` |
| Vertical flow | `column` |
| Column/row spans | `grid` |
| Overlays or background plates | `layers` |
| Surface plus child content | `box` |
| Fixed placement on a slide | `slide.compose(node, { frame })` or facade `position` |
Use `frame` for the outer composed region. Inside the region, use `row`,
`column`, `grid`, and `layers` so content stays resizable and inspectable. Use
`layers` plus image `geometry`/`borderRadius` for overlays, scrims, and masked
image compositions inside a region.
## Sizing Vocabulary
```tsx
<box width="fill" height="fill" /> // claim available space
<box width="hug" height="hug" /> // fit its children
<box width={320} height={180} /> // fixed pixels
```
Equal siblings fill equally:
```tsx
<row width="fill" height={160} gap={24} align="stretch">
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
</row>
```
One fixed sibling plus one flexible sibling:
```tsx
<row width="fill" height="fill" gap={32} align="stretch">
<column width={360} height="fill" gap={16}>
<paragraph className="text-slate-950 text-4xl font-bold">Fixed rail</paragraph>
<paragraph className="text-slate-600 text-lg">This column stays 360px wide.</paragraph>
</column>
<box width="fill" height="fill" className="bg-slate-100 rounded-2xl" />
</row>
```
## Padding And Gutters
Use object padding for asymmetric page gutters. Use numeric padding for all
sides.
Use an 8px spacing scale unless matching a source deck: common gaps are `16`,
`24`, `28`, and `32`. Common page gutters use `PAGE`; pass `baseUnit: 8` to
`slide.compose` when examples rely on this scale.
```tsx
<column
width="fill"
height="fill"
padding={{ top: 64, right: 80, bottom: 56, left: 80 }}
gap={28}
>
<paragraph className="text-slate-950 text-5xl font-bold">Page title</paragraph>
<box width="fill" height="fill" className="bg-white rounded-xl" />
</column>
```
```tsx
<box width="fill" height="hug" padding={{ x: 28, y: 18 }} className="bg-sky-50 rounded-xl">
<paragraph className="text-sky-950 text-xl font-bold">Compact padded box</paragraph>
</box>
```
## Rows
`row` lays out children left to right. `justify` distributes along the
horizontal axis. `align` controls vertical alignment.
```tsx
<row width="fill" height={72} align="center" justify="between">
<paragraph className="text-slate-950 text-2xl font-bold">Left</paragraph>
<paragraph className="text-slate-500 text-sm">Right</paragraph>
</row>
```
Center a child:
```tsx
<row width="fill" height={220} align="center" justify="center">
<box width={360} height={120} className="bg-white rounded-xl shadow-sm" />
</row>
```
Stretch all children to the row height:
```tsx
<row width="fill" height={240} gap={20} align="stretch">
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
</row>
```
## Columns
`column` lays out children top to bottom. `justify` distributes along the
vertical axis. `align` controls horizontal alignment.
```tsx
<column width="fill" height="fill" justify="between" gap={24}>
<paragraph className="text-slate-950 text-4xl font-bold">Top block</paragraph>
<paragraph className="text-slate-600 text-lg">Bottom block</paragraph>
</column>
```
Metadata row, content region, and closing rule:
```tsx
<column width="fill" height="fill" gap={24}>
<row width="fill" height={72} align="center" justify="between">
<paragraph className="text-slate-500 text-sm font-bold">HEADER</paragraph>
<paragraph className="text-slate-400 text-sm">Source</paragraph>
</row>
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<rule stroke="slate-200" weight={1} />
</column>
```
## Three Columns
Use a `row` when all columns are equal or only one side is fixed.
```tsx
slide.compose(
<row name="three-column-layout" width="fill" height="fill" gap={24} align="stretch">
<column name="column-a" width="fill" height="fill" gap={12}>
<paragraph className="text-slate-950 text-2xl font-bold">Column A</paragraph>
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
</column>
<column name="column-b" width="fill" height="fill" gap={12}>
<paragraph className="text-slate-950 text-2xl font-bold">Column B</paragraph>
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
</column>
<column name="column-c" width="fill" height="fill" gap={12}>
<paragraph className="text-slate-950 text-2xl font-bold">Column C</paragraph>
<paragraph className="text-slate-600 text-base">Editable body copy.</paragraph>
</column>
</row>,
{ frame: PAGE, baseUnit: 8 },
);
```
Use fixed rails when the center should absorb resize:
```tsx
<row width="fill" height="fill" gap={24} align="stretch">
<box width={240} height="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" height="fill" className="bg-white rounded-xl" />
<box width={240} height="fill" className="bg-slate-50 rounded-xl" />
</row>
```
## Twelve-Column Grid
Use `grid` when child spans matter. Keep `fr` and fixed track objects local and
obvious; use the literal `"auto"` for auto tracks:
```tsx
const GRID_12 = Array.from(
{ length: 12 },
() => ({ mode: "fr", value: 1 }) as const,
);
```
Use a 12-column grid when spans communicate structure. Spans in a row usually
add to 12, such as `4/4/4`, `3/6/3`, or `4/8`. Put vertical content inside
`column` children and surfaces inside `box` children. Use a simple `row` when
every column is equal and no span semantics are needed.
Full-width heading plus three equal columns:
```tsx
<grid
width="fill"
height="fill"
columns={GRID_12}
rows={["auto", { mode: "fr", value: 1 }]}
columnGap={24}
rowGap={28}
>
<paragraph columnSpan={12} className="text-slate-950 text-5xl font-bold">
Full-width heading
</paragraph>
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box columnSpan={4} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
</grid>
```
Four/eight split:
```tsx
<grid width="fill" height="fill" columns={GRID_12} columnGap={28}>
<column columnSpan={4} width="fill" height="fill" gap={16}>
<paragraph className="text-slate-950 text-4xl font-bold">Left span</paragraph>
<paragraph className="text-slate-600 text-lg">Uses 4 of 12 columns.</paragraph>
</column>
<box columnSpan={8} width="fill" height="fill" className="bg-sky-50 rounded-2xl" />
</grid>
```
Three/six/three split:
```tsx
<grid width="fill" height="fill" columns={GRID_12} columnGap={20}>
<box columnSpan={3} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box columnSpan={6} width="fill" height="fill" className="bg-white rounded-xl shadow-sm" />
<box columnSpan={3} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
</grid>
```
Rows plus row spans:
```tsx
<grid
width="fill"
height="fill"
columns={GRID_12}
rows={["auto", { mode: "fr", value: 1 }, { mode: "fr", value: 1 }]}
columnGap={24}
rowGap={24}
>
<paragraph columnSpan={12} className="text-slate-950 text-4xl font-bold">
Heading
</paragraph>
<box columnSpan={8} rowSpan={2} width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box columnSpan={4} width="fill" height="fill" className="bg-sky-50 rounded-xl" />
<box columnSpan={4} width="fill" height="fill" className="bg-emerald-50 rounded-xl" />
</grid>
```
Mixed fixed and flexible tracks:
```tsx
<grid
width="fill"
height="fill"
columns={[
{ mode: "fixed", value: 280 },
{ mode: "fr", value: 1 },
{ mode: "fixed", value: 220 },
]}
columnGap={24}
>
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" height="fill" className="bg-white rounded-xl shadow-sm" />
<box width="fill" height="fill" className="bg-slate-50 rounded-xl" />
</grid>
```
## Grid Alignment
Use `alignItems` and `justifyItems` for grid child alignment. If one child
needs different alignment, wrap it in a `row`, `column`, or `box`.
| Node | Main axis | Cross axis | Distribution prop | Cross-axis prop | Defaults |
| --- | --- | --- | --- | --- | --- |
| `row` | horizontal | vertical | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `start` / `start` |
| `column` | vertical | horizontal | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `start` / `start` |
| `grid` | tracks | cells | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | `stretch` / `stretch` |
| `layers` | shared frame | shared frame | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | `stretch` / `stretch` |
```tsx
<grid
width="fill"
height={260}
columns={[{ mode: "fr", value: 1 }, { mode: "fr", value: 1 }]}
rows={[{ mode: "fr", value: 1 }]}
columnGap={24}
alignItems="center"
justifyItems="stretch"
>
<box height={120} className="bg-slate-50 rounded-xl" />
<box height="fill" className="bg-sky-50 rounded-xl" />
</grid>
```
## Layers
`layers` gives every child the same parent frame. Put visual backgrounds first,
then overlays, then editable text.
```tsx
<layers width="fill" height="fill">
<image
blob={backgroundBytes}
contentType="image/jpeg"
fit="cover"
alt="Background"
width="fill"
height="fill"
/>
<shape geometry="rect" width="fill" height="fill" fill="black/45" />
<column width={620} height="fill" padding={64} justify="end" gap={18}>
<paragraph className="text-white text-5xl font-bold leading-tight">
Editable headline
</paragraph>
<paragraph className="text-white/80 text-xl leading-relaxed">
Editable supporting copy.
</paragraph>
</column>
</layers>
```
## Image Masks
Use image `geometry` for real clipping. Use `crop` plus `fit="cover"` when the
subject should fill the mask.
Quick reference:
| Need | Use |
| --- | --- |
| Preserve the full image | `fit="contain"` |
| Fill the frame and allow crop | `fit="cover"` |
| Clip to a shape | `geometry="ellipse"` or `geometry="roundRect"` |
| Rounded rectangle mask | `borderRadius="rounded-2xl"` |
| Manual crop | `crop={{ left, top, right, bottom }}` with normalized `0..1` insets |
`crop` values are fractions removed from each source-image edge and are clamped.
Overlays do not clip images; use image `geometry` or `borderRadius` for masks.
```tsx
<image
blob={portraitBytes}
contentType="image/jpeg"
alt="Portrait"
geometry="ellipse"
fit="cover"
crop={{ left: 0.1, top: 0, right: 0.08, bottom: 0 }}
width={240}
height={240}
/>
```
Rounded rectangle image:
```tsx
<image
blob={photoBytes}
contentType="image/jpeg"
alt="Photo"
fit="cover"
width="fill"
height={320}
borderRadius="rounded-2xl"
/>
```
## Flow Versus Absolute Placement
Use flow for related content:
```tsx
slide.compose(
<column width="fill" height="fill" gap={20}>
<paragraph className="text-slate-950 text-4xl font-bold">Title</paragraph>
<row width="fill" height="fill" gap={24} align="stretch">
<box width="fill" className="bg-slate-50 rounded-xl" />
<box width="fill" className="bg-slate-50 rounded-xl" />
</row>
</column>,
{ frame: PAGE, baseUnit: 8 },
);
```
Use absolute positions for elements that must land at exact slide coordinates:
```ts
slide.shapes.add({
geometry: "rect",
name: "fixed-accent-bar",
position: { left: 0, top: 0, width: 12, height: 720 },
fill: "accent1",
line: { style: "solid", fill: "none", width: 0 },
});
```
## Verify Layout
Inspect the layout tree when spans or wrapping matter:
```ts
const layout = await slide.export({ format: "layout" });
const png = await slide.export({ format: "png", scale: 1 });
const snapshot = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart",
maxChars: 8000,
});
```
Check the rendered PNG for clipping, overlap, broken image crops, and text
that should have stayed editable.
@@ -0,0 +1,201 @@
# Fill And Line Configs
Fill configs style shapes, chart regions, table cells, slide backgrounds, lines,
and text fills. Text outlines use `LineConfig`, so their `fill`/`color` fields
accept the same fill forms.
## Fill Forms
```ts
shape.fill = fillConfig;
shape.line = lineConfig;
```
Supported fill forms:
- Theme, hex, RGB/RGBA, Tailwind-like color, and transformed color strings.
- `"none"` and `"transparent"`.
- Gradient strings such as `linear(...)` and `radial(...)`.
- `{ type: "none" }`.
- `{ type: "solid", color, pattern }`.
- `{ type: "gradient", gradientKind, angleDeg, stops }`.
- `{ type: "image", imageReference, srcRect, fillRect, stretchFillRect }`.
## String Fill Shortcuts
Use string fills for compact JSX and facade setters:
```tsx
<shape geometry="rect" fill="none" line={{ style: "solid", fill: "slate-300", width: 1 }} />
<box fill="black/45" />
<box fill="transparent" />
<box fill="accent1+18/90" />
<box fill="linear(135deg, #ffffff 0%, sky-100 58%, #ffffff/0 100%)" />
<shape geometry="ellipse" fill="radial(white/80 0%, emerald-200/45 48%, emerald-700/0 100%)" />
```
Use `fill="none"` when the object should have no fill. Use
`fill="transparent"` when the object should keep an editable transparent solid
fill.
`+` lightens theme/RGB colors, `-` darkens, and `/` sets opacity. Tailwind-like
color tokens, theme aliases, gradients, shadows, and text style strings are
summarized in `tokens.md`.
## Fill Inline Types
```ts
type ThemeColorName =
| "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
| "bg1" | "bg2" | "tx1" | "tx2" | "dk1" | "lt1" | "dk2" | "lt2"
| "hlink" | "folHlink";
type ColorConfig =
| string
| { type: "rgb"; value: string; transform?: ColorTransform }
| { type: "theme"; value: ThemeColorName; transform?: ColorTransform };
type ColorTransform = {
opacity?: number; // 0..1 or 0..100
lighten?: number; // 0..1 or 0..100
darken?: number; // 0..1 or 0..100
};
type FillConfig =
| string
| { type: "none" }
| { type: "solid"; color: ColorConfig; pattern?: PatternConfig }
| {
type: "gradient";
stops: Array<{ offset: number; color: ColorConfig }>; // offset 0..100000
offsetScale?: 1 | 100000;
angleDeg?: number;
gradientKind?: "linear" | "path";
}
| {
type: "image";
imageReference: { id: string };
alphaModFix?: number;
stretchFillRect?: { l?: number; t?: number; r?: number; b?: number };
fillRect?: { l?: number; t?: number; r?: number; b?: number };
srcRect?: { l?: number; t?: number; r?: number; b?: number };
};
```
## Gradient
```ts
const fillConfig = {
type: "gradient",
gradientKind,
angleDeg,
stops: [
{ offset: startOffset, color: startColor },
{ offset: endOffset, color: endColor },
],
};
```
Gradient offsets use `0` to `100000`.
## Pattern Fills
Patterns are available through object fill configs:
```ts
shape.fill = {
type: "solid",
color: "white",
pattern: { type: "diagonalCross", color: "slate-300/70" },
};
```
Common compact pattern names:
```text
percent10, percent20, lightHorizontal, lightVertical, smallGrid, dotGrid,
diagonalCross, narrowVertical, wave, smallCheck
```
Supported pattern names:
```text
none, solid, mediumGray, darkGray, lightGray, darkHorizontal, darkVertical,
darkDown, darkUp, darkGrid, darkTrellis, lightHorizontal, lightVertical,
lightDown, lightUp, lightGrid, lightTrellis, gray125, gray0625, percent5,
percent10, percent20, percent25, percent30, percent40, percent50, percent60,
percent70, percent75, percent80, percent90, horizontal, vertical,
narrowHorizontal, narrowVertical, dashedHorizontal, dashedVertical, cross,
largeGrid, smallGrid, dotGrid, downwardDiagonal, upwardDiagonal,
wideDownwardDiagonal, wideUpwardDiagonal, dashedDownwardDiagonal,
dashedUpwardDiagonal, diagonalCross, smallCheck, largeCheck, smallConfetti,
largeConfetti, horizontalBrick, diagonalBrick, solidDiamond, openDiamond,
dottedDiamond, plaid, sphere, weave, divot, shingle, wave, trellis, zigZag
```
## Line
```ts
const lineConfig = {
style: lineStyle,
fill: lineFill,
width: lineWidthPx,
};
```
## Line Inline Type
```ts
type LineConfig = {
style: "solid" | "dashed" | "dotted" | "dash-dot" | "dash-dot-dot" | string;
fill?: FillConfig;
width?: number;
color?: FillConfig; // alias for fill
weight?: number; // alias for width
};
```
## Cookbook
```ts
// Linear background wash.
slide.background.fill = "linear(0deg, #020617 0%, #2563eb 100%)";
```
```ts
// Soft radial spotlight behind a chart.
chart.plotAreaFill = "radial(#dbeafe/90 0%, #ffffff/0 100%)";
```
```ts
// Exact gradient object.
shape.fill = {
type: "gradient",
gradientKind: "linear",
angleDeg: 35,
offsetScale: 100000,
stops: [
{ offset: 0, color: "#ffffff" },
{ offset: 100000, color: "sky-100" },
],
};
```
```ts
// Normalized gradient offsets.
shape.fill = {
type: "gradient",
gradientKind: "linear",
offsetScale: 1,
stops: [
{ offset: 0, color: "#ffffff" },
{ offset: 1, color: "sky-100" },
],
};
```
```ts
// Hairline rule and muted border.
shape.line = { style: "solid", fill: "slate-200", width: 1 };
ruleShape.line = { style: "dashed", fill: "#94a3b8", width: 1 };
```
@@ -0,0 +1,223 @@
# Help
Use `presentation.help(...)` to search the presentation JS API and template
catalog. Help emits bounded NDJSON records for quick lookup during create, edit,
and review workflows.
## Query
```ts
const result = presentation.help(query, {
search,
include,
maxChars,
});
console.log(result.ndjson);
```
Example output for `query = "*"` with `include = ["index", "examples"]`:
```text
{"kind":"api","name":"presentation.help","summary":"Search the presentation JS API and template catalog.","tags":["help","docs","examples","presentation.help"],"examples":[{"summary":"Find shape editing APIs","code":"const result = presentation.help('*', {\n search: 'slide.shapes.delete|shape.delete|slide.shapes.add|deleteAll',\n include: ['index', 'examples', 'notes'],\n maxChars: 12000,\n});\nconsole.log(result.ndjson);"}]}
{"kind":"api","name":"slide.shapes.add","summary":"Add a preset/custom/connector shape to a slide.","tags":["shape","shapes.add","rectangle","ellipse","connector","slide.shapes.add"],"examples":[{"summary":"Create a styled rectangle","code":"const shape = slide.shapes.add({\n geometry: 'roundRect',\n position: { left: 72, top: 96, width: 320, height: 120 },\n fill: { type: 'solid', color: 'accent1' },\n line: { style: 'solid', fill: 'accent2', width: 2 },\n});\nshape.text = 'Launch plan';"}]}
{"kind":"template","name":"agenda","summary":"Agenda slide with a title and list body.","examples":[{"summary":"Apply the agenda template","code":"presentation.apply(presentation.template('agenda'));"}]}
```
Use API records to find facade names and examples; use template records with
`presentation.template(name)`.
Common queries:
```text
*, shape*, slide.shapes.add, chart xAxis, template*
```
Query behavior:
```text
* lists all matching API and template records
shape* uses glob matching
slide.shapes.add matches the exact dotted API name
chart xAxis matches entries containing either word token
template* lists template records only
```
Use `search` as a case-insensitive regular expression over the JSON lines after
the primary query has selected records:
```ts
const focused = presentation.help("*", {
search:
"slide\\.shapes\\.delete|shape\\.delete|slide\\.shapes\\.add|deleteAll",
include: ["index", "examples", "notes"],
maxChars: 12000,
});
console.log(focused.ndjson);
```
## Include
Default output includes index fields such as:
```text
kind, name, summary, tags
```
Useful include tokens:
```text
index, examples, notes
```
`include` accepts either an array or a comma-separated string:
```ts
const shapeExamples = presentation.help("slide.shapes.add", {
include: ["examples", "notes"],
});
const templateExamples = presentation.help("template*", {
include: "index,examples",
});
```
## Inline Type
```ts
type PresentationHelpOptions = {
include?: string[] | string;
search?: string;
maxChars?: number;
};
type PresentationHelpResult = {
ndjson: string;
truncated: boolean;
metadata: {
revision: string;
query: string;
include: {
requested?: string[] | string;
tokens: string[];
};
search?: string;
notices?: string[];
};
};
```
## Record Kinds
API records describe public JS facades and methods:
```text
{"kind":"api","name":"slide.shapes.add","summary":"Add a preset/custom/connector shape to a slide.","tags":["shape","shapes.add","rectangle","ellipse","connector","slide.shapes.add"]}
{"kind":"api","name":"shape.delete","summary":"Delete this shape from its slide.","tags":["shape","delete shape","remove shape","shape.delete"]}
```
When examples are included, records focus on usage snippets:
```text
{"kind":"api","name":"slide.shapes.add","examples":[{"summary":"Create a styled rectangle","code":"const shape = slide.shapes.add({\n geometry: 'roundRect',\n position: { left: 72, top: 96, width: 320, height: 120 },\n fill: { type: 'solid', color: 'accent1' },\n line: { style: 'solid', fill: 'accent2', width: 2 },\n});\nshape.text = 'Launch plan';"}],"notes":["Preset geometry values include rect, roundRect, ellipse, triangle, rightArrow, and many other PowerPoint shape names."]}
```
Template records describe named template patches for
`presentation.template(name)`:
```text
{"kind":"template","name":"title-slide","summary":"Title + subtitle slide with centered text boxes."}
{"kind":"template","name":"two-up","summary":"Two-column slide with left/right content boxes."}
{"kind":"template","name":"agenda","summary":"Agenda slide with a title and list body."}
```
If output exceeds `maxChars`, the final line is a notice record and
`result.truncated` is `true`:
```text
{"kind":"notice","message":"Truncated: omitted 93 lines. Increase maxChars or narrow query."}
```
## Create/Edit Loop
```ts
// Find the public API surface for the edit.
const shapeHelp = presentation.help("shape*", {
include: ["index", "examples", "notes"],
maxChars: 8000,
});
// Build with the documented JS facade.
const slide = presentation.slides.add();
const shape = slide.shapes.add({
geometry: "roundRect",
position: { left: 72, top: 96, width: 320, height: 120 },
fill: { type: "solid", color: "accent1" },
});
shape.text = "Launch plan";
// Inspect the live deck after editing.
const snapshot = await presentation.inspect({
kind: "slide,textbox,shape",
maxChars: 4000,
});
```
## Imported Templates
```ts
const templates = presentation.help("template*", {
include: ["index", "examples"],
maxChars: 4000,
});
presentation.apply(presentation.template("agenda"));
```
Use template help to discover the available names before calling
`presentation.template(name)`.
## Cookbook
```ts
// List the top-level deck APIs.
const deckApis = presentation.help("presentation*", {
include: "index",
maxChars: 6000,
});
```
```ts
// Search broadly, then filter by regex.
const hits = presentation.help("*", {
search: "chart|axis|legend",
include: ["index", "examples"],
maxChars: 8000,
});
```
```ts
// Pull examples for one exact API.
const examples = presentation.help("slide.charts.add", {
include: ["examples", "notes"],
maxChars: 4000,
});
```
```ts
// Pair help with inspect for focused edits.
const help = presentation.help("shape.text.replace", {
include: ["examples", "notes"],
});
const before = await presentation.inspect({
kind: "textbox,shape",
search: "Placeholder",
maxChars: 4000,
});
const target = presentation.resolve(anchorId);
target.text.replace("Placeholder", "Updated text");
const after = await presentation.inspect({
target: { id: anchorId, beforeLines: 2, afterLines: 2 },
kind: "textbox,shape",
maxChars: 2000,
});
```
@@ -0,0 +1,286 @@
# Images
`slide.images` inserts image elements from local paths, bytes, data URLs, SVG, and prompts.
For embedded image output, use `blob={imageBytes}` with `contentType`. Download remote images
first, then pass their local `path` or embedded `blob` bytes to `add` or `replace`.
HTTP(S) sources are rejected without fetching them.
## Add Image
```ts
const image = slide.images.add({
blob: imageBytes,
contentType: "image/png",
alt: "Product screenshot",
fit: "cover",
position: { left: 72, top: 120, width: 520, height: 320 },
crop: { left: 0.02, top: 0, right: 0.04, bottom: 0 },
geometry: "roundRect",
borderRadius: "rounded-2xl",
});
```
## Path Reference And Inline SVG
```ts
const localImage = slide.images.add({
path: "/absolute/path/to/product.png",
alt: "Product screenshot from disk",
fit: "cover",
position: { left: 72, top: 120, width: 520, height: 320 },
});
const icon = slide.images.add({
svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10" fill="#2563eb"/></svg>',
alt: "Blue status icon",
position: { left: 620, top: 120, width: 48, height: 48 },
});
```
## Image Inline Types
```ts
type ImageSource =
| { path: string; prompt?: string }
| { svg: string; prompt?: string }
| { blob: ArrayBuffer | Uint8Array; prompt?: string }
| { dataUrl: string; prompt?: string }
| { prompt: string };
type ImageAddOptions = ImageSource & {
alt?: string;
fit?: "contain" | "cover";
contentType?: string;
position?: { left?: number; top?: number; width?: number; height?: number };
frame?: { left?: number; top?: number; width?: number; height?: number };
crop?: { left: number | string; top: number | string; right: number | string; bottom: number | string };
geometry?: string; // common: "rect", "roundRect", "ellipse"; full list is the shape preset list
borderRadius?: number | string; // number = pixels; string = supported rounded-* token
};
```
`position` and `frame` use the same pixel shape. Use either spelling; prefer
`position` in add calls and `frame` when preserving imported placement.
## Resolved From Inspect
```ts
const image = presentation.resolve("im/c3d4e5f6");
const oldFrame = image.frame;
const oldCrop = image.crop;
const oldFit = image.fit;
const oldAlt = image.alt;
const oldPrompt = image.prompt;
const oldGeometry = image.geometry;
const oldBorderRadius = image.borderRadius;
const oldRotation = image.rotation;
const oldFlipHorizontal = image.flipHorizontal;
const oldFlipVertical = image.flipVertical;
const oldLockAspectRatio = image.lockAspectRatio;
image.replace({
blob: nextBytes,
contentType: "image/png",
alt: oldAlt ?? "Updated screenshot",
...(oldFit ? { fit: oldFit } : {}),
...(oldPrompt ? { prompt: oldPrompt } : {}),
});
image.frame = oldFrame;
image.crop = oldCrop;
image.geometry = oldGeometry;
image.borderRadius = oldBorderRadius;
image.rotation = oldRotation;
image.flipHorizontal = oldFlipHorizontal;
image.flipVertical = oldFlipVertical;
image.lockAspectRatio = oldLockAspectRatio;
```
Use `presentation.inspect({ kind: "image", search })` to find the `im/...`
anchor id. Preserve frame, crop, fit, alt text, mask geometry, and border radius
unless the edit explicitly changes them.
Concrete source replacements produce concrete images; pass `prompt` when it
should remain available as regeneration metadata.
## Edit Placement And Fit
```ts
image.position = position;
image.frame = frame;
image.fit = fit;
image.crop = crop;
image.geometry = "roundRect";
image.borderRadius = "rounded-xl";
image.rotation = rotationDeg;
image.flipHorizontal = flipHorizontal;
image.flipVertical = flipVertical;
image.lockAspectRatio = true;
image.width = 320;
image.height = 180;
image.alt = altText;
```
`crop` supplies all four edges. Numbers are normalized `0..1` fractions removed
from the source image; strings accept percentages such as `"10%"` or pixel
insets such as `"24px"` when source dimensions are available. Values are clamped.
`fit="cover"` fills the frame and may crop; `fit="contain"`
preserves the full image. `geometry="ellipse"` or `geometry="roundRect"` clips
the image. `borderRadius` is for rect/roundRect masks; numbers are pixels and
strings use supported `rounded-*` tokens.
## Replace Source
```ts
image.replace({
blob,
contentType,
path,
svg,
dataUrl,
prompt,
alt,
fit,
});
```
`replace` swaps the source and common source metadata. Choose one primary source
field as with `add`. Preserve or set placement, crop, mask geometry, and border
radius on the image facade itself.
## Replace And Regenerate Inline Types
```ts
type ImageReplaceOptions = {
alt?: string;
fit?: "contain" | "cover";
contentType?: string;
path?: string;
svg?: string;
blob?: ArrayBuffer | Uint8Array;
dataUrl?: string;
prompt?: string;
};
type ImageRegenerateOptions = {
prompt?: string;
kind?: "sticker" | "layout" | "content" | "infographic";
fit?: "contain" | "cover";
size?: "1024x1024" | "1536x1024" | "1024x1536";
quality?: "low" | "medium" | "high";
background?: "auto" | "transparent" | "opaque";
outputFormat?: "png" | "jpeg" | "webp";
};
```
## Prompt Images
```ts
const promptImage = slide.images.add({
prompt,
alt,
position,
fit,
});
promptImage.regenerate({ kind });
```
Prompt placeholders are optional. Use concrete sources when asset bytes or
references are already available.
## Concrete Image Sources
```ts
const imageBytes = assetBytes;
const imageUri = assetUri;
const imageDataUrl = assetDataUrl;
```
## JSX Declarative Image
```tsx
/** @jsxRuntime automatic */
slide.compose(
<row width="fill" height="fill" gap={16}>
<image
blob={imageBytes}
alt="Embedded bytes"
fit="cover"
width={320}
height={180}
/>
<image
path={imagePath}
alt="Local image"
fit="contain"
width={320}
height={180}
/>
</row>,
{
frame: { left: 48, top: 40, width: 864, height: 240 },
baseUnit: 8,
},
);
```
## Cookbook
```ts
// Full-frame image crop.
slide.images.add({
blob: imageBytes,
contentType: "image/jpeg",
alt: "Workspace image",
fit: "cover",
position: { left: 0, top: 0, width: 1280, height: 720 },
});
```
```ts
// Rounded image mask.
slide.images.add({
blob: imageBytes,
contentType: "image/jpeg",
alt: "Customer interview",
fit: "cover",
geometry: "roundRect",
borderRadius: "rounded-3xl",
position: { left: 720, top: 96, width: 448, height: 512 },
});
```
```tsx
// Circular avatar mask in JSX.
<image
blob={avatarBytes}
contentType="image/png"
alt="Speaker"
fit="cover"
geometry="ellipse"
width={96}
height={96}
/>
```
```tsx
// Rounded crop/mask in JSX.
<image
blob={portraitBytes}
contentType="image/jpeg"
alt="Customer portrait"
fit="cover"
geometry="roundRect"
borderRadius="rounded-2xl"
crop={{ left: 0.08, top: 0.02, right: 0.14, bottom: 0 }}
width={320}
height={420}
/>
```
```ts
// Manual crop when the subject is off-center.
image.fit = "cover";
image.crop = { left: 0.08, top: 0.02, right: 0.18, bottom: 0.06 };
```
@@ -0,0 +1,131 @@
# Inspect
`presentation.inspect({ select, include, fileName })` queries one public
presentation tree with [RFC 9535 JSONPath](https://www.rfc-editor.org/rfc/rfc9535.html).
The [JSON Schema](./inspect.schema.json) describes its content and layout fields.
`select` finds nodes; `include` chooses exact fields from those nodes.
## Read content
```ts
await presentation.inspect({
select: "$.slides[*]",
include: [
"id", "index", "layout", "title",
"elements.id", "elements.kind", "elements.text", "elements.alt", "elements.title",
"notes.text",
],
fileName: "content.ndjson",
});
```
This writes one slide per line, retaining its applied layout and editable
element IDs. Text includes paragraph breaks and complete table content. The
query omits positions and styles, so those fields are not computed.
The tree has this shape (selected fields):
```json
{
"schema": "openai.presentation.inspection/v1",
"unit": "px",
"id": "pr/abcdefgh",
"kind": "presentation",
"slides": [{
"id": "sl/12345678", "kind": "slide", "index": 0,
"layout": { "id": "ly/abcdefgh", "name": "Title and image" },
"elements": [{ "id": "sh/abcdefgh", "kind": "textbox", "text": "Welcome" }],
"notes": { "id": "nt/12345678", "kind": "notes", "text": "Opening remarks" }
}]
}
```
Only canonical prefix/hash IDs are exposed. Pass editable `sl/`, `sh/`, `im/`,
`ch/`, `tb/`, `ea/`, and `nt/` IDs to `presentation.resolve(id)`.
The read-only `ly/` ID identifies the applied layout. `index` is zero-based;
positions and computed font sizes use pixels.
## Find and edit
```ts
const hits = await presentation.inspect({
select: "$.slides[*].elements[?(@.text == 'Confidential')]",
include: ["id", "text"],
});
```
JSONPath filters inspect source fields before projection. Comparisons therefore
match the text itself, rather than its serialized JSON representation. Use
`$.slides[0,2].elements[*]` for two slides or a predicate such as
`@.kind == 'image'` for one element kind. Selected scalar values are also valid;
for example, `$.slides[*].title` returns title strings.
Use `search(@.text, 'overview|steps')` for a text pattern, or `match()` to match
the entire string. Patterns follow [I-Regexp](https://www.rfc-editor.org/rfc/rfc9485.html).
`length()` measures a value, `count()` counts selected nodes, and `value()`
extracts a value when a query selects exactly one node. Filters use `==` and
`!=`; JavaScript expressions and method calls are not part of JSONPath.
Repeated selectors retain repeated results: `$.slides[0,0]` selects slide zero
twice. Invalid queries report a syntax error with the character offset.
Use the literal ID from the result for subsequent edits. Read computed styling
or mixed-format text for that same ID:
```ts
await presentation.inspect({
select: "$.slides[*].elements[?(@.id == 'sh/abcdefgh')]",
include: ["id", "text", "position", "style", "paragraphs"],
});
```
`style` reflects theme and inherited formatting. `paragraphs` preserves styled
runs; `cells` expands a table. These fields are evaluated when accessed without
rendering slides or fetching images. Explicit paths keep queries focused;
recursive `..` queries can traverse computed fields across the document.
`include` is an exact array of typed field paths. Nested paths such as
`elements.text` preserve arrays and object structure. Including a parent such
as `style` includes that complete object. Omitting `include` returns complete
selected nodes. Include `id` explicitly when the next step needs an editing ID.
## Files and results
An attached Artifact Session writes all selected records to
`<outputDirectory>/presentation-inspect.ndjson`. `fileName` chooses another
NDJSON basename. Reusing a name replaces that file. The completed session run's
`files` contains finalized paths. Unnamed inspection outside a session stays in
memory; the Node runtime supports a named standalone output path.
The returned object prints `recordCount` and output metadata. Access `.records`
or `.ndjson` explicitly for the complete values. No pagination or record
abbreviation applies to JSONPath queries. Select nodes and fields according to
the task before reading the output into model context.
Rendering separately writes `slide-N.png` and `slide-N.layout.json`. Layout
files use these same element fields and canonical IDs in a slide-scoped file
envelope. The file's `slide` contains the inspected slide metadata and its
`elements` contains the compact layout field selection. The content query does
not replace those render outputs. Full layout export also exposes inherited
paint layers and paragraph/run formatting.
## Types
```ts
type PresentationInspectQueryOptions = {
select: string;
include?: readonly PresentationInspectField[];
fileName?: string;
};
type PresentationInspectQueryResult = {
readonly records: readonly unknown[];
readonly recordCount: number;
readonly ndjson: string;
readonly path?: string;
readonly status?: "pending" | "saved" | "conflict" | "error";
readonly message?: string;
};
```
The earlier preset and record-filter overloads remain deprecated compatibility
entry points. New callers should use the explicit query above.
@@ -0,0 +1,865 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"schema": {
"type": "string",
"const": "openai.presentation.inspection/v1"
},
"unit": {
"type": "string",
"const": "px"
},
"id": {
"type": "string",
"pattern": "^pr\\/[a-z0-9]+$"
},
"kind": {
"type": "string",
"const": "presentation"
},
"slides": {
"type": "array",
"items": {
"$ref": "#/$defs/Slide"
}
}
},
"required": [
"schema",
"unit",
"id",
"kind",
"slides"
],
"additionalProperties": false,
"$defs": {
"Slide": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^sl\\/[a-z0-9]+$"
},
"kind": {
"type": "string",
"const": "slide"
},
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"layout": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ly\\/[a-z0-9]+$"
},
"name": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
},
"title": {
"type": "string"
},
"position": {
"$ref": "#/$defs/Position"
},
"backgroundColor": {
"$ref": "#/$defs/Color"
},
"elements": {
"type": "array",
"items": {
"$ref": "#/$defs/Element"
}
},
"notes": {
"$ref": "#/$defs/Notes"
},
"inheritedLayers": {
"type": "array",
"items": {
"$ref": "#/$defs/InheritedLayer"
}
}
},
"required": [
"id",
"kind",
"index",
"position",
"elements"
],
"additionalProperties": false,
"id": "Slide"
},
"Position": {
"type": "object",
"properties": {
"left": {
"type": "number"
},
"top": {
"type": "number"
},
"width": {
"type": "number"
},
"height": {
"type": "number"
}
},
"required": [
"left",
"top",
"width",
"height"
],
"additionalProperties": false,
"id": "Position"
},
"Color": {
"anyOf": [
{
"type": "string"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "rgb"
},
"value": {
"type": "string"
},
"transform": {
"type": "object",
"properties": {
"opacity": {
"type": "number"
},
"lighten": {
"type": "number"
},
"darken": {
"type": "number"
}
},
"additionalProperties": false
}
},
"required": [
"type",
"value"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "theme"
},
"value": {
"type": "string",
"enum": [
"accent1",
"accent2",
"accent3",
"accent4",
"accent5",
"accent6",
"bg1",
"bg2",
"tx1",
"tx2",
"dk1",
"lt1",
"dk2",
"lt2",
"hlink",
"folHlink"
]
},
"transform": {
"type": "object",
"properties": {
"opacity": {
"type": "number"
},
"lighten": {
"type": "number"
},
"darken": {
"type": "number"
}
},
"additionalProperties": false
}
},
"required": [
"type",
"value"
],
"additionalProperties": false
}
],
"id": "Color"
},
"Element": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
},
"kind": {
"type": "string",
"enum": [
"shape",
"textbox",
"image",
"chart",
"table",
"embeddedArtifact"
]
},
"name": {
"type": "string"
},
"text": {
"type": "string"
},
"title": {
"type": "string"
},
"position": {
"$ref": "#/$defs/Position"
},
"order": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"scope": {
"type": "string",
"enum": [
"slide",
"layout",
"master"
]
},
"editable": {
"type": "boolean"
},
"rotation": {
"type": "number"
},
"horizontalFlip": {
"type": "boolean"
},
"verticalFlip": {
"type": "boolean"
},
"hidden": {
"type": "boolean"
},
"geometry": {
"type": "string"
},
"style": {
"$ref": "#/$defs/TextStyle"
},
"paragraphs": {
"type": "array",
"items": {
"$ref": "#/$defs/Paragraph"
}
},
"fillColor": {
"$ref": "#/$defs/Color"
},
"lineColor": {
"$ref": "#/$defs/Color"
},
"lineWidth": {
"type": "number"
},
"alt": {
"type": "string"
},
"chartType": {
"type": "string"
},
"rows": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"cols": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"contentType": {
"type": "string"
},
"crop": {
"type": "object",
"properties": {
"left": {
"type": "number"
},
"top": {
"type": "number"
},
"right": {
"type": "number"
},
"bottom": {
"type": "number"
}
},
"required": [
"left",
"top",
"right",
"bottom"
],
"additionalProperties": false
},
"fit": {
"type": "string"
},
"mask": {
"type": "object",
"properties": {
"geometry": {
"type": "string"
},
"adjustmentList": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"formula": {
"type": "string"
}
},
"additionalProperties": false
}
}
},
"required": [
"geometry"
],
"additionalProperties": false
},
"prompt": {
"type": "string"
},
"isPlaceholder": {
"type": "boolean"
},
"asset": {
"$ref": "#/$defs/Asset"
},
"fillImage": {
"$ref": "#/$defs/Asset"
},
"tableCell": {
"type": "object",
"properties": {
"tableId": {
"type": "string",
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
},
"cellIndex": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"row": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"column": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"overlap": {
"type": "number"
}
},
"required": [
"tableId",
"cellIndex",
"row",
"column",
"overlap"
],
"additionalProperties": false
},
"cells": {
"type": "array",
"items": {
"$ref": "#/$defs/TableCell"
}
}
},
"required": [
"id",
"kind"
],
"additionalProperties": false,
"id": "Element"
},
"TextStyle": {
"type": "object",
"properties": {
"anchor": {
"type": "number"
},
"vertical": {
"type": "number"
},
"rotation": {
"type": "number"
},
"fontSize": {
"type": "number"
},
"name": {
"type": "string"
},
"family": {
"type": "number"
},
"scheme": {
"type": "string"
},
"typeface": {
"type": "string"
},
"color": {
"$ref": "#/$defs/Color"
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"alignment": {
"type": "string",
"enum": [
"left",
"center",
"right",
"justify"
]
},
"verticalAlignment": {
"type": "string",
"enum": [
"top",
"middle",
"bottom"
]
},
"lineSpacing": {
"type": "number"
},
"textTransform": {
"type": "string",
"enum": [
"none",
"uppercase",
"smallCaps"
]
},
"wrap": {
"type": "string",
"enum": [
"square",
"none"
]
},
"autoFit": {
"type": "string",
"enum": [
"none",
"shrinkText",
"resizeShapeToFitText"
]
},
"autoFitScale": {
"type": "number"
},
"autoFitLineSpaceReduction": {
"type": "number"
},
"insets": {
"type": "object",
"properties": {
"top": {
"type": "number"
},
"right": {
"type": "number"
},
"bottom": {
"type": "number"
},
"left": {
"type": "number"
}
},
"additionalProperties": false
},
"useParagraphSpacing": {
"type": "boolean"
}
},
"additionalProperties": false,
"id": "TextStyle"
},
"Paragraph": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"text": {
"type": "string"
},
"bulletCharacter": {
"type": "string"
},
"marginLeft": {
"type": "number"
},
"indent": {
"type": "number"
},
"lineSpacingPercent": {
"type": "number"
},
"spaceBefore": {
"type": "number"
},
"spaceAfter": {
"type": "number"
},
"style": {
"$ref": "#/$defs/TextStyle"
},
"runs": {
"type": "array",
"items": {
"$ref": "#/$defs/TextRun"
}
}
},
"required": [
"index",
"runs"
],
"additionalProperties": false,
"id": "Paragraph"
},
"TextRun": {
"type": "object",
"properties": {
"anchor": {
"type": "number"
},
"vertical": {
"type": "number"
},
"rotation": {
"type": "number"
},
"fontSize": {
"type": "number"
},
"name": {
"type": "string"
},
"family": {
"type": "number"
},
"scheme": {
"type": "string"
},
"typeface": {
"type": "string"
},
"color": {
"$ref": "#/$defs/Color"
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"alignment": {
"type": "string",
"enum": [
"left",
"center",
"right",
"justify"
]
},
"verticalAlignment": {
"type": "string",
"enum": [
"top",
"middle",
"bottom"
]
},
"lineSpacing": {
"type": "number"
},
"textTransform": {
"type": "string",
"enum": [
"none",
"uppercase",
"smallCaps"
]
},
"wrap": {
"type": "string",
"enum": [
"square",
"none"
]
},
"autoFit": {
"type": "string",
"enum": [
"none",
"shrinkText",
"resizeShapeToFitText"
]
},
"autoFitScale": {
"type": "number"
},
"autoFitLineSpaceReduction": {
"type": "number"
},
"insets": {
"type": "object",
"properties": {
"top": {
"type": "number"
},
"right": {
"type": "number"
},
"bottom": {
"type": "number"
},
"left": {
"type": "number"
}
},
"additionalProperties": false
},
"useParagraphSpacing": {
"type": "boolean"
},
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"text": {
"type": "string"
}
},
"required": [
"index",
"text"
],
"additionalProperties": false,
"id": "TextRun"
},
"Asset": {
"type": "object",
"properties": {
"contentType": {
"type": "string"
},
"uri": {
"type": "string"
},
"prompt": {
"type": "string"
},
"byteLength": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"additionalProperties": false,
"id": "Asset"
},
"TableCell": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"row": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"column": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"rowSpan": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"colSpan": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"position": {
"$ref": "#/$defs/Position"
},
"text": {
"type": "string"
},
"textDirection": {
"type": "string"
},
"fillColor": {
"$ref": "#/$defs/Color"
},
"style": {
"$ref": "#/$defs/TextStyle"
},
"paragraphs": {
"type": "array",
"items": {
"$ref": "#/$defs/Paragraph"
}
},
"ownedElementIds": {
"type": "array",
"items": {
"type": "string",
"pattern": "^(sh|im|ch|tb|ea)\\/[a-z0-9]+$"
}
}
},
"required": [
"index",
"row",
"column"
],
"additionalProperties": false,
"id": "TableCell"
},
"Notes": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^nt\\/[a-z0-9]+$"
},
"kind": {
"type": "string",
"const": "notes"
},
"text": {
"type": "string"
}
},
"required": [
"id",
"kind",
"text"
],
"additionalProperties": false,
"id": "Notes"
},
"InheritedLayer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^ly\\/[a-z0-9]+$"
},
"scope": {
"type": "string",
"enum": [
"layout",
"master"
]
},
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"parentLayoutId": {
"type": "string",
"pattern": "^ly\\/[a-z0-9]+$"
},
"backgroundColor": {
"$ref": "#/$defs/Color"
},
"backgroundImage": {
"$ref": "#/$defs/Asset"
},
"elements": {
"type": "array",
"items": {
"$ref": "#/$defs/Element"
}
}
},
"required": [
"id",
"scope",
"elements"
],
"additionalProperties": false,
"id": "InheritedLayer"
}
}
}
@@ -0,0 +1,227 @@
# Presentation JSX Reference
This is the compact API reference for authoring editable presentations with
presentation JSX. It describes the node vocabulary and layout mechanics. For
first-principles row, column, grid, alignment, mask, and overlay recipes, read
`cookbook/layout.md`.
Examples start after `presentation` and `slide` exist.
## Authoring Defaults
- Use JSX for structured slide layout: `slide.compose(<row ... />, { frame })`.
- Use string sizing where supported: `width="fill"`, `height="hug"`,
`height="fill"`.
- Use raw pixel numbers for fixed sizes: `width={420}`, `gap={24}`,
`padding={{ x: 48, y: 40 }}`.
- Use Tailwind-like tokens for common styling: `fill="slate-950"`,
`borderRadius="rounded-xl"`, `shadow="shadow-md"`,
`className="bg-white rounded-xl shadow-sm"`.
- Use `row`, `column`, `grid`, `layers`, and `box` for layout. Use absolute
slide frames only for the outer composed region, fixed chrome, and
imported-template details. For overlays, scrims, and masked image
compositions inside a region, use `layers` and image `geometry`/`borderRadius`.
- Put text in `paragraph` and inline emphasis in child `run` nodes.
- Put real data in native `table` and `chart` nodes.
- Model-facing examples use string sizing and local track objects instead of
imported sizing helpers such as `wrap(...)`, `grow(...)`, and `fr(...)`.
## JSX Usage Rules
Use JSX props for layout and token strings for common visual styling:
| Need | Use |
| --- | --- |
| Layout sizing | `width="fill"`, `height={320}`, `gap={24}`, `padding={{ x: 32, y: 24 }}` |
| Flex flow | `<row align="center" justify="between">` and `<column gap={16}>` |
| Grid tracks | local arrays such as `[{ mode: "fr", value: 1 }]` |
| Visual tokens | `className="bg-white rounded-xl shadow-sm"` |
| Exact text | `style="font: 700 28px Inter; color: #0f172a; leading: 1.1"` |
| Gradients | `fill="linear(135deg, #fff 0%, sky-100 100%)"` |
| Image masks | `<image geometry="ellipse" crop={...} fit="cover" />` |
## Canonical Node Set
### Slide Roots
| Node | Purpose | Common props |
| --- | --- | --- |
| `slide` | Whole-slide JSX root | `id`, `name`, `width`, `height`, `padding`, `gap`, `align`, `justify`, `background`, `backgroundRef` |
| `background` | Slide background metadata | `fill`, `ref` |
Most code composes directly into an existing `slide` facade rather than using a
`<slide>` root.
### Layout Nodes
| Node | Purpose | Common props |
| --- | --- | --- |
| `row` | Horizontal flex-like layout | `width`, `height`, `gap`, `align`, `justify`, `padding` |
| `column` | Vertical flex-like layout | `width`, `height`, `gap`, `align`, `justify`, `padding` |
| `grid` | Track layout with spans | `columns`, `rows`, `autoRows`, `columnGap`, `rowGap`, `alignItems`, `justifyItems`, `padding` |
| `layers` | Overlay children in one frame | `width`, `height`, `padding`, `alignItems`, `justifyItems` |
| `box` | Surface/container with one child region | `width`, `height`, `padding`, `align`, `justify`, `fill`, `line`, `borderRadius`, `shadow`, `className` |
`align` controls the cross axis. `justify` controls the main axis. Supported
values are `"start"`, `"center"`, `"end"`, `"stretch"` for alignment and
`"start"`, `"center"`, `"end"`, `"between"` for distribution.
All direct grid children support `columnSpan` and `rowSpan`, including
`row`, `column`, `box`, `paragraph`, `shape`, `image`, `table`, and `chart`.
### Content Nodes
| Node | Purpose | Common props |
| --- | --- | --- |
| `paragraph` | Text block | `width`, `height`, `style`, `className`, `transform`, `bulletCharacter`, `marginLeft`, `indent`, `spaceBefore`, `spaceAfter`, `styleId`, `paragraphStyle` |
| `run` | Inline text run | children, `textStyle`, `className`, `link` |
| `shape` | Primitive drawing | `geometry`, `width`, `height`, `fill`, `line`, `borderRadius`, `shadow`, `className` |
| `image` | Raster/vector image | `path`, `blob`, `dataUrl`, `svg`, `prompt`, `contentType`, `fit`, `alt`, `geometry`, `borderRadius`, `crop`, `rotation`, `flipHorizontal`, `flipVertical`, `lockAspectRatio`, `width`, `height` |
| `rule` | Divider line | `stroke`, `weight`, `opacity`, `width`, `height` |
| `table` | Native table | `rows`, `columns`, `values`, `style`, `styleOptions`, `width`, `height` |
| `chart` | Native chart | `chartType`, `title`, `categories`, `series`, `legend`, `xAxis`, `yAxis`, `width`, `height` |
`id` and `name` are supported on materialized nodes. Use deterministic
kebab-case `name` values on composed roots and important descendants:
`content-frame`, `primary-heading`, `metrics-grid`, `chart-frame`, `revenue-chart`.
Names should describe role, not visual position. Use `id` when the calling code
controls stability across edits.
### Chart Child Nodes
Use a compact chart config when it is clearest. Use nested chart nodes when the
JSX tree should expose structure.
| Node | Purpose |
| --- | --- |
| `bar`, `line`, `area`, `scatter`, `bubble`, `radar`, `pie`, `doughnut`, `treemap`, `sunburst`, `map`, `waterfall`, `funnel`, `histogram`, `boxWhisker`, `stock`, `surface`, `surface3D`, `pareto`, `combo`, `line3D`, `pie3D`, `area3D`, `bar3D`, `ofPie` | Chart family selector/options |
| `legend`, `data-labels`, `data-table`, `x-axis`, `y-axis`, `axis`, `major-gridlines`, `minor-gridlines` | Chart chrome and axes |
| `series`, `marker`, `point`, `data-label`, `trendline`, `trendline-label`, `error-bars` | Series and point-level options |
| `view-3d` | 3D camera options |
## Sizing And Frames
Use these forms first:
| Intent | JSX |
| --- | --- |
| Fill parent | `width="fill"` or `height="fill"` |
| Fit content | `width="hug"` or `height="hug"` |
| Fixed pixels | `width={320}` or `height={180}` |
| Equal children in a row/column | give each child `width="fill"` or `height="fill"` |
| One fixed region plus remaining space | one child `width={520}`, sibling `width="fill"` |
| Fixed slide region | `slide.compose(node, { frame: { left, top, width, height } })` |
`frame` uses numeric pixels. JSX size props accept strings for `"fill"` and
`"hug"` plus raw pixel numbers.
Use `1280 x 720` as the default canvas unless the task or source deck requires
another size. A common content frame is:
```ts
const PAGE = { left: 72, top: 64, width: 1136, height: 592 };
```
## Alignment Matrix
| Node | Main axis | Cross axis | Distribution prop | Cross-axis prop | Defaults |
| --- | --- | --- | --- | --- | --- |
| `row` | horizontal | vertical | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `justify="start"`, `align="start"` |
| `column` | vertical | horizontal | `justify`: `start`, `center`, `end`, `between` | `align`: `start`, `center`, `end`, `stretch` | `justify="start"`, `align="start"` |
| `grid` | tracks | cells | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | both `stretch` |
| `layers` | shared frame | shared frame | `justifyItems`: `start`, `center`, `end`, `stretch` | `alignItems`: `start`, `center`, `end`, `stretch` | both `stretch` |
## Layout Recipes
This top-level reference stays close to the JSX API. For copy-paste row,
column, 3-column, 12-grid, alignment, mask, overlay, and gradient recipes, use
[`cookbook/layout.md`](./cookbook/layout.md).
## Text Examples
```tsx
<paragraph className="text-slate-950 text-4xl font-bold leading-tight">
A paragraph can contain plain text.
</paragraph>
<paragraph className="text-slate-600 text-lg leading-relaxed">
Use <run textStyle={{ bold: true, color: "sky-600" }}>runs</run> for inline
emphasis or links.
</paragraph>
<column width="fill" height="hug" gap={8}>
<paragraph
width="fill"
className="text-slate-700 text-lg leading-relaxed"
>
First paragraph.
</paragraph>
<paragraph bulletCharacter="•" marginLeft={18} indent={-10}>
Bulleted paragraph with native list metadata.
</paragraph>
</column>
```
Use `style={{ ... }}` for exact text config and `className` for tokenized
common text styling. A string `style` containing `:` or `;` is parsed as a
compact text declaration; any other string is treated as a named presentation
style id.
```tsx
<paragraph style="font: 700 22px Inter; color: #334155; leading: 1.25; wrap: none">
Exact style string
</paragraph>
```
## Tables And Charts
Prefer compact config for data objects.
```tsx
<table
rows={3}
columns={3}
values={[
["Metric", "Q1", "Q2"],
["Revenue", 12, 18],
["Margin", "42%", "45%"],
]}
style="TableStyleMedium2"
styleOptions={{ headerRow: true, bandedRows: true }}
width="fill"
height={220}
/>
<chart
chartType="bar"
title="Pipeline"
categories={["Q1", "Q2", "Q3"]}
series={[{ name: "Revenue", values: [12, 18, 24], fill: "sky-500" }]}
xAxis={{ textStyle: { fontSize: 10, fill: "slate-600" } }}
yAxis={{ majorGridlines: { style: "solid", fill: "slate-200", width: 1 } }}
width="fill"
height={280}
/>
```
Use nested chart nodes when the chart needs explicit series, point, trendline,
axis, or label structure in the JSX tree.
## Image Sources
| Source prop | Use when |
| --- | --- |
| `blob={bytes}` | Export must embed the actual image bytes. |
| `dataUrl="data:image/..."` | Bytes are already encoded inline. |
| `path="/assets/image.png"` | A downloaded image is available as a local file. |
| `prompt="..."` | The slide should contain an image-generation placeholder. |
Use `fit="contain"` when the full image must remain visible. Use `fit="cover"`
when cropping is deliberate. Keep labels and data as editable slide text layered
with the image.
## Reference Tests
- `tests/presentation/jsx.spec.tsx`: JSX normalization and compose behavior.
- `tests/presentation/jsx-style-language.spec.tsx`: compact style strings.
- `tests/presentation/tailwind-tokens.sanity.spec.ts`: token coverage.
@@ -0,0 +1,155 @@
# Layouts
Layouts define reusable placeholder structure for slides.
## Create A Layout
```ts
const layout = presentation.layouts.add(layoutName);
layout.placeholders.add({
type: placeholderType,
index: placeholderIndex,
text: placeholderText,
geometry: "textbox",
});
```
## Placeholder Inline Type
```ts
type PlaceholderConfig = {
type?:
| "title"
| "subtitle"
| "body"
| "picture"
| "chart"
| "table"
| "content";
index?: number;
text?: TextValue;
geometry?: "textbox" | "rect" | "roundRect" | string;
position?: { left?: number; top?: number; width?: number; height?: number };
fill?: FillConfig;
line?: LineConfig;
};
```
## Shape-Based Placeholders
```ts
const placeholder = layout.shapes.addPlaceholder(placeholderName);
placeholder.placeholder.type = placeholderType;
placeholder.placeholder.index = placeholderIndex;
placeholder.text = placeholderText;
```
## Use A Layout
```ts
slide.setLayout(layout);
const target = slide.placeholders.getItem(placeholderType);
target.text = textValue;
```
## Discover
```ts
const layoutSummary = layout.placeholders.summary();
const resolved = presentation.layouts.getById(layout.id);
const importedGuides = layout.slideGuides;
const actualPlaceholders = slide.placeholders.items;
const emptyContentPlaceholders = slide.placeholders.editable;
const allVisibleEmptyPlaceholders = slide.placeholders.unfilled;
const missingLayoutSlots = slide.placeholders.availableFromLayout;
```
These getters do not modify saved slide content.
`items` includes filled placeholders. `editable` contains visible empty content
shapes with positive bounds; `unfilled` also includes empty furniture.
`availableFromLayout` contains missing layout slots for explicit creation.
`getAll()` retains layout/master discovery, and `getItem()` creates a local
instance when the requested placeholder exists only in the layout or master.
## Preview And Insert A Layout
```ts
presentation.view.showPlaceholders();
const image = await layout.export({ format: "png", scale: 0.25 });
const { slide } = presentation.slides.insert({
after: selectedSlide,
layoutId: layout.id,
});
slide.placeholders.addFromLayout();
slide.placeholders.getItem("title").text = titleText;
```
`addFromLayout()` creates missing content placeholders once and returns the
created shapes. Adding a slide alone leaves placeholder creation to the caller.
## Cookbook
```ts
// Branded title/body layout.
const layout = presentation.layouts.add("Title Body");
layout.placeholders.add({
type: "title",
index: 0,
geometry: "textbox",
position: { left: 72, top: 64, width: 920, height: 88 },
text: "Title",
});
layout.placeholders.add({
type: "body",
index: 0,
geometry: "roundRect",
position: { left: 72, top: 180, width: 760, height: 360 },
fill: "slate-50",
line: { style: "solid", fill: "slate-200", width: 1 },
});
```
```ts
// Use placeholders for repeated structure; override slide content locally.
const slide = presentation.slides.add({ layout: "Title Body" });
slide.placeholders.getItem("title").text = "Market overview";
slide.placeholders.getItem("body").text = "Three editable points go here.";
```
## Read A Rendered Slide's Layout
Each `presentation.render()` preview is an image Blob with a `.layout` JSON Blob.
The paired files use the same stem, for example `slide-1.png` and
`slide-1.layout.json`. A complete render replaces the previous render set;
a subset render updates only the selected slides' pairs.
```ts
const preview = await presentation.render({ slide: 0 });
const layout = JSON.parse(await preview.layout.text());
const title = layout.elements.find((element) => element.name === "cover-title");
if (title) presentation.resolve(title.id).text = "Updated title";
```
The default `openai.presentation.layout/v5` view is compact and uses pixels and
canonical IDs. Request `slide.export({ format: "layout", detail: "full" })` for
inherited paint layers, paragraph/run formatting, and table-cell details.
Both views use the same IDs and editing coordinates:
| Field | Meaning |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `slide.id`, `slide.index` | Canonical slide ID and zero-based deck index. |
| `slide.position` | Slide bounds: `{ left, top, width, height }`. |
| `elements[].id`, `kind`, `name` | Canonical element ID, element kind, and optional authored name. |
| `elements[].position` | Bounds using the same keys as edit configuration. |
| `elements[].text`, `style` | Text and effective text styling, including `style.fontSize`. |
| `elements[].crop`, `fit`, `mask` | Image crop, fitting, and geometry configuration. |
| `elements[].scope`, `editable` | Owned slide content is editable; inherited layout/master content is identified separately. |
| `tableCell.tableId`, `cells[].ownedElementIds` | Canonical IDs connecting a table, its cells, and cell-owned elements. |
| `inheritedLayers[].id` | Canonical `ly/…` ID of a layout or master. |
Pass IDs from editable records to `presentation.resolve()` or
`presentation.delete()`. In the full view, inherited content has `editable: false`; its IDs identify
where the content came from and are not slide-owned edit targets. Raw PowerPoint
IDs, asset IDs, and paragraph style IDs are not part of this public view.
@@ -0,0 +1,57 @@
# Masters
Masters share theme, background, and color-map structure with child layouts.
## Create And Link
```ts
const master = presentation.masters.add(masterName);
const layout = presentation.layouts.add(layoutName);
layout.setParentLayoutId(master.id);
```
## Color Map And Background
```ts
master.setColorMap(colorMapConfig);
master.background.ref = backgroundRef;
const slide = presentation.slides.add();
slide.setLayout(layout);
```
## Master Inline Types
```ts
type ColorMapConfig = Partial<Record<
"bg1" | "tx1" | "bg2" | "tx2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink",
"bg1" | "tx1" | "bg2" | "tx2" | "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6" | "hlink" | "folHlink"
>>;
```
## Resolve
```ts
const resolved = presentation.layouts.getById(master.id);
```
## Cookbook
```ts
// Shared brand master with inherited layout.
const master = presentation.masters.add("Brand Master");
master.setColorMap({ bg1: "bg1", tx1: "tx1", accent1: "accent1" });
master.background.ref = "bg1";
const layout = presentation.layouts.add("Brand Title");
layout.setParentLayoutId(master.id);
layout.placeholders.add({
type: "title",
geometry: "textbox",
position: { left: 72, top: 72, width: 1000, height: 96 },
});
```
Before editing a master in an imported deck, inspect affected layouts and
slides; master edits have intentional global blast radius.
@@ -0,0 +1,291 @@
# Presentation Facade
## Create And Load
```ts
const presentation = Presentation.create({ slideSize });
const loaded = await Presentation.load("input.pptx");
const imported = Presentation.load(proto);
```
## Create Inline Type
```ts
type PresentationCreateOptions = {
slideSize?: { width: number; height: number };
};
```
## Presentation Slide Collection
```ts
const slide = presentation.slides.add({ layout, layoutId, background: { fill } });
const inserted = presentation.slides.insert({ after, layout, layoutId });
const byIndex = presentation.slides.getItem(slideIndex);
presentation.slides.keep([0, 2, 4]);
presentation.slides.reorder(orderedSlideIds);
```
`keep` accepts an array of zero-based indexes or an array of canonical `sl/` IDs.
It validates the selection against the current slide list, then preserves the
selected slides in their existing relative order. Repeated selections are ignored;
an empty array deletes all slides. `reorder` requires the complete desired order,
with every current slide ID exactly once. Invalid selections fail before mutation.
## Presentation Slide Collection Inline Types
```ts
type SlideAddOptions = {
layout?: string;
layoutId?: string;
width?: number;
height?: number;
background?: { fill: FillConfig };
};
type SlideInsertOptions = SlideAddOptions & {
after?: Slide | number | null;
};
interface SlideCollection {
keep(selection: readonly number[] | readonly string[]): void;
reorder(ids: readonly string[]): void;
}
interface Presentation {
delete(ids: string | readonly string[]): void;
}
```
## Discover And Edit
```ts
const snapshot = await presentation.inspect({
kind,
search,
limit,
offset,
});
const target = presentation.resolve(anchorId);
const targets = presentation.resolve(anchorIds);
presentation.delete(anchorIds);
```
`delete` accepts one canonical ID or an array. It supports slides (`sl/`) and owned
shapes, images, charts, tables, and embedded artifacts (`sh/`, `im/`, `ch/`, `tb/`,
`ea/`). All IDs are validated first. Repeated IDs are ignored; selecting a slide
and its children deletes the slide once. Inherited elements, notes, text ranges,
and the presentation itself are not delete targets.
`inspect` returns stable anchor ids for slides, shapes, images, tables, charts, text ranges, speaker notes, and comment threads. `resolve` maps one anchor id to its facade, or an array of ids to facades in the same order. Layout records expose canonical `ly/...` IDs with `editable: false` for search and comparison; pass only `pr/`, `sl/`, `sh/`, `im/`, `tb/`, `ch/`, `nt/`, `th/`, and `tr/` anchors to `resolve`.
## Inspect
Use `presentation.inspect({ select, include, fileName })` with JSONPath over the
public presentation tree. `include` is an exact array of typed fields, including
nested paths such as `elements.text`. The query writes all selected records to
NDJSON in the session output directory; ordinary printing shows the count and
file metadata. See [Inspect](./inspect.md) and the
[inspection JSON Schema](./inspect.schema.json) for content and layout queries.
## Help
```ts
const help = presentation.help(query, {
search,
include,
maxChars,
});
```
## Help Inline Type
```ts
type PresentationHelpOptions = {
search?: string;
include?: string[]; // common: ["index", "examples", "notes"]
maxChars?: number;
};
```
## Presentation View
```ts
presentation.view.showGridlines();
presentation.view.showGuides();
presentation.view.showPlaceholders();
const gridlinesVisible = presentation.view.gridlinesVisible;
const guidesVisible = presentation.view.guidesVisible;
const placeholdersVisible = presentation.view.placeholdersVisible;
const horizontalGridSpacingEmu = presentation.view.gridSpacingCxEmu;
const verticalGridSpacingEmu = presentation.view.gridSpacingCyEmu;
presentation.view.hideGridlines();
presentation.view.hideGuides();
presentation.view.hidePlaceholders();
const nextGridlineState = presentation.view.toggleGridlines();
const nextGuideState = presentation.view.toggleGuides();
const nextPlaceholderState = presentation.view.togglePlaceholders();
```
## Render And Export
```ts
const overview = await presentation.render({ montage: true, fileName: "overview.png" });
const selectedPreviews = await presentation.render({ slide: [0, 2] }); // PNG/layout pairs
const allPreviews = await presentation.render(); // pairs in deck order
const firstPreview = await presentation.render({ slide: 0 }); // one image Blob with .layout
const pptxBlob = await presentation.export({ format: "pptx", fileName: "presentation.pptx" });
const deckPdfBlob = await presentation.export({ format: "pdf" });
const slidePdfBlob = await presentation.export({ slide, format: "pdf" });
const layoutBlob = await slide.export({ format: "layout" });
const proto = presentation.toProto();
```
### Montage overview
`render({ montage: true })` includes every slide in deck order, regardless of
which slide is active. It returns one image Blob without per-slide layout files.
The default format is PNG and the default filename is `presentation-montage.png`.
A custom `fileName` names the overview. In an Artifact Session, it is published
as one render output under the session output directory.
Read the montage and content inspection first, then render selected slides for
full-size PNGs and companion layout JSON files. A montage cannot combine with
`slide`; use a separate selected render for detailed text and layout review.
Pass a montage options object to configure the grid. Dimensions are pixels before
`scale`. Defaults are 320 pixels per slide, 16 pixels of padding and gap, and
`ceil(sqrt(slideCount))` columns. Slides retain their aspect ratios; each row uses
its tallest slide's height. `montage.width` sets the total width and overrides
`slideWidth`. `montage.format` overrides the outer raster format. Widths and scale
must be positive and finite, columns must be a positive integer, and padding and
gap must be nonnegative and finite. Montages support PNG, JPEG, and WebP.
### Individual slide previews
Without a montage, `render()` defaults to every slide. An omitted `slide` or an
index array returns an array of image Blobs; a single index or `Slide` returns one
image Blob. Selected arrays preserve their requested order. Default output names
use the actual slide number, such as `slide-1.png` and `slide-3.png` for
`slide: [0, 2]`. A custom `fileName` requires a single selected slide.
Each returned image Blob has a `.layout` JSON Blob containing the same slide's
layout view. Session outputs publish both files as render outputs with matching
stems, such as `slide-1.png` and `slide-1.layout.json`. Full-deck renders replace
both parts of the previous render set; subset renders update only the selected
pairs. Rendering a montage does not replace that per-slide set. See
[the layout reference](layout.spec.md#read-a-rendered-slides-layout) for the schema.
An empty deck or empty selection returns `[]` for individual slide rendering.
Use `export({ format: "pptx" })` for the editable deliverable. Existing raster
and montage `export` options remain supported; raster `export` without a montage
retains its single-active-slide default.
Use `export({ format: "pdf" })` for one PDF containing every slide in deck order,
or pass `slide` to export one slide as PDF.
## Render And Export Inline Types
```ts
type PresentationMontageOptions = {
format?: "png" | "jpeg" | "webp";
width?: number;
slideWidth?: number;
padding?: number;
gap?: number;
background?: string;
columns?: number;
};
type PresentationExportOptions = {
fileName?: string;
slide?: Slide;
format?: "png" | "jpeg" | "webp" | "pdf" | "layout" | "pptx";
width?: number;
height?: number;
scale?: number;
quality?: number;
montage?: boolean | PresentationMontageOptions;
};
type PresentationRenderOptions = Omit<
PresentationExportOptions,
"format" | "slide"
> & {
format?: "png" | "jpeg" | "webp";
slide?: Slide | number | number[];
};
type PresentationRenderResult = Blob & { layout: Blob };
interface Presentation {
render(options: PresentationRenderOptions & { montage: true | PresentationMontageOptions; slide?: never }): Promise<Blob>;
render(options: PresentationRenderOptions & { montage?: false; slide: Slide | number }): Promise<PresentationRenderResult>;
render(options?: PresentationRenderOptions & { montage?: false; slide?: number[] }): Promise<PresentationRenderResult[]>;
}
```
## Scripts
```ts
const result = presentation.scripts.run(scriptKind, scriptOptions);
```
Scripts provide high-level authoring recipes. Use `presentation.help(...)` to discover available script keys and option shapes.
## Cookbook
```ts
// New deck skeleton: create, set theme, add slides, render checks.
const presentation = Presentation.create({
slideSize: { width: 1280, height: 720 },
});
presentation.theme.colorScheme = {
name: "Clean Product",
themeColors: {
accent1: "#2563eb",
accent2: "#0f766e",
accent3: "#f59e0b",
accent4: "#dc2626",
accent5: "#7c3aed",
accent6: "#16a34a",
bg1: "#ffffff",
bg2: "#f8fafc",
tx1: "#0f172a",
tx2: "#475569",
dk1: "#000000",
dk2: "#1e293b",
lt1: "#ffffff",
lt2: "#e2e8f0",
hlink: "#2563eb",
folHlink: "#7c3aed",
},
};
const first = presentation.slides.add();
const second = presentation.slides.add();
const third = presentation.slides.add();
await presentation.render({
slide: first,
scale: 1,
});
const snapshot = await presentation.inspect({
kind: "deck,slide,textbox,chart,table",
limit: 20,
});
```
```ts
// Existing deck: inspect first, then resolve exact anchors.
const before = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart,notes,thread,layout",
search: "Customer growth",
limit: 20,
});
const target = presentation.resolve(anchorIdFromBefore);
```
@@ -0,0 +1,256 @@
# Rich Text
Shape text accepts strings, paragraph arrays, and structured runs.
## Set Text
```ts
shape.text = textValue;
shape.text = paragraphs;
shape.text = structuredRuns;
```
## Text Value Inline Types
```ts
type TextValue = string | string[] | StructuredTextInput | Text;
type StructuredTextInput =
| ParagraphRunsInput
| StructuredTextParagraphInput
| Array<ParagraphRunsInput | StructuredTextParagraphInput>;
type ParagraphRunsInput = Array<string | number | TextRunInput>;
type StructuredTextParagraphInput = {
runs?: ParagraphRunsInput;
bulletCharacter?: string;
marginLeft?: number;
indent?: number;
spaceBefore?: number;
spaceAfter?: number;
styleId?: string;
paragraphStyle?: Record<string, unknown>;
};
type TextRunInput = {
run: string;
style?: {
bold?: boolean;
italic?: boolean;
underline?: string;
fontSize?: string;
typeface?: string;
color?: FillConfig;
};
textStyle?: TextRunInput["style"]; // Compatibility alias.
link?: { uri: string; isExternal: boolean; action?: string };
};
```
`style` takes precedence as a complete object when both `style` and `textStyle` are supplied.
Structured run `fontSize` accepts unit strings such as `"20pt"` and `"28px"`.
Shape text style setters use numeric pixels with `fontSize` and numeric points
with `fontSizePt`.
## Structured Paragraphs
```ts
shape.text.set([
[{ run: "Status", style: { bold: true } }, { run: " review" }],
{
bulletCharacter: "•",
marginLeft: 18,
indent: -10,
runs: [
"Open the",
{
run: " rollout notes",
style: { underline: "sng", color: "#2563eb" },
link: { uri: "https://example.com", isExternal: true },
},
],
},
]);
```
The paragraph-object form is the non-JSX peer of `<paragraph>...</paragraph>`. Use it when the text needs paragraph metadata plus authored runs.
## JSX Rich Text
```tsx
/** @jsxRuntime automatic */
slide.compose(
<column width="fill" height="hug" gap={8}>
<paragraph width="fill" className="text-slate-950 text-2xl leading-tight">
<run textStyle={{ bold: true }}>Status</run>
<run> review</run>
</paragraph>
<paragraph
width="fill"
className="text-slate-950 text-2xl leading-tight"
bulletCharacter="•"
marginLeft={18}
indent={-10}
>
Open the
<run
textStyle={{ underline: "sng", color: "#2563eb" }}
link={{ uri: "https://example.com", isExternal: true }}
>
{" rollout notes"}
</run>
</paragraph>
</column>,
{
frame: { left: 48, top: 40, width: 864, height: 160 },
baseUnit: 8,
},
);
```
## Shape Text Style
```ts
shape.text.style = {
styleName,
fontSize: fontSizePx,
color: colorConfig,
fill: fillConfig,
outline: lineConfig,
alignment,
verticalAlignment,
autoFit: autoFitMode,
wrap: wrapMode,
insets,
};
```
Use grouped `text.style = { ... }` for whole-shape text formatting. Use single
property setters for focused edits:
```ts
shape.text.fontSize = fontSizePx;
shape.text.color = colorConfig;
shape.text.fill = fillConfig;
shape.text.outline = lineConfig;
shape.text.alignment = alignment;
shape.text.verticalAlignment = verticalAlignment;
shape.text.autoFit = autoFitMode;
shape.text.wrap = wrapMode;
shape.text.insets = 0; // Set all four sides; use an object for individual sides.
```
`shape.text.color` uses `ColorConfig`. `shape.text.fill`, run `style.fill`,
and text ranges accept the shared `FillConfig`, including linear and path
gradients. `shape.text.outline`, run `style.outline`, and text ranges accept
`LineConfig`; the outline line fill can be a solid, pattern, or gradient fill.
```ts
shape.text.fill = {
type: "gradient",
gradientKind: "linear",
angleDeg: 0,
stops: [
{ offset: 0, color: "#ff5a5f" },
{ offset: 100000, color: "#4f46e5" },
],
};
```
Path gradients use the same fill config with `gradientKind: "path"`, `pathType`, and optional
`fillRect` in thousandths of a percent (`100000` = 100%).
## Text Style Inline Type
```ts
type TextStyleConfig = {
styleName?: string;
className?: string;
bold?: boolean;
italic?: boolean;
fontSize?: number;
lineSpacing?: number;
alignment?: "left" | "center" | "right" | "justify";
verticalAlignment?: "top" | "middle" | "bottom";
underline?: string;
fill?: FillConfig;
color?: ColorConfig;
outline?: LineConfig;
wrap?: "square" | "none";
autoFit?: "none" | "shrinkText" | "resizeShapeToFitText";
insets?: number | { top?: number; right?: number; bottom?: number; left?: number };
typeface?: string;
};
```
## Ranges
```ts
const range = shape.text.get(searchText);
range.bold = isBold;
range.italic = isItalic;
range.fill = fillConfig;
range.outline = lineConfig;
range.link = linkConfig;
const fixedRange = shape.text.getRange(start, length);
fixedRange.style = styleName;
```
## Lists
```ts
shape.text = listParagraphs;
shape.text.style = listStyleName;
shape.text.get(itemText).lineSpacing = lineSpacing;
```
## Links
```ts
shape.text.get(linkText).link = {
uri,
isExternal,
};
```
## Link Inline Type
```ts
type LinkConfig = {
uri: string;
isExternal: boolean;
action?: string;
};
```
## Cookbook
```ts
// Title with emphasized suffix.
shape.text.set([
[
{ run: "Revenue", style: { bold: true, color: "#0f172a" } },
{ run: " momentum", style: { color: "#2563eb" } },
],
]);
shape.text.style = { fontSize: 44, lineSpacing: 0.92 };
```
```ts
// Bullets with bold lead-ins.
shape.text.set([
{ bulletCharacter: "•", marginLeft: 22, indent: -12, runs: [{ run: "Quality:", style: { bold: true } }, " defect rate down 31%"] },
{ bulletCharacter: "•", marginLeft: 22, indent: -12, runs: [{ run: "Speed:", style: { bold: true } }, " p95 latency under target"] },
]);
```
```ts
// Edit one phrase inside imported text.
const range = shape.text.get("legacy workflow");
range.text = "new workflow";
range.className = "text-emerald-700 font-bold";
```
@@ -0,0 +1,279 @@
# Shapes
`slide.shapes` creates and edits drawable slide elements.
## Preset Shape
```ts
const shape = slide.shapes.add({
geometry,
name,
position,
fill,
line,
adjustmentList,
borderRadius,
shadow,
className,
text: { text: textValue, style: { styleName: textStyleName, fontSize, bold, color } },
});
shape.position = nextPosition;
```
`geometry` is a string preset shape name, `"textbox"`, `"connector"`, or `"custom"`.
Set `shape.text.insets = 0` to remove all text margins. A number sets every side;
an object sets individual sides. Creation styles also accept `insets: 0`.
## Resolved From Inspect
```ts
const shape = presentation.resolve("sh/a1b2c3d4");
shape.text = "Updated copy";
shape.fill = "accent1+18/90";
shape.line = { style: "solid", fill: "slate-200", width: 1 };
shape.geometry = "roundRect";
shape.geometry; // "roundRect"
shape.borderRadius = "rounded-2xl";
shape.shadow = "shadow-sm";
```
Use `presentation.inspect({ kind: "shape,textbox", search })` to find the
`sh/...` anchor id. Keep the resolved facade type-aware; do not rebuild an
imported shape unless the task requires a new object.
## Preset Shape Inline Type
```ts
type ShapePresetName = string; // common: "textbox", "rect", "roundRect", "ellipse", "line", "rightArrow"
// Full preset list: rg "SHAPE_GEOMETRY_NAME_TO_PROTO" src/models/presentation src/assets
type PositionConfig = {
left?: number;
top?: number;
width?: number;
height?: number;
rotation?: number;
horizontalFlip?: boolean;
verticalFlip?: boolean;
};
type PresetShapeConfig = {
geometry: ShapePresetName;
name?: string;
position?: PositionConfig;
fill?: FillConfig;
line?: LineConfig;
adjustmentList?: Array<{ name: string; formula: string }>;
borderRadius?: number | string; // number = pixels; string = supported rounded-* token
shadow?: string; // shadow token, "shadow-none", or custom "2px 7px 19px #000000/17"
className?: string;
text?: TextValue | { text: TextValue; style?: string | ShapeTextStyleConfig };
placeholderType?: "title" | "subtitle" | "body" | "picture" | "chart" | "table" | "content";
placeholderIndex?: number;
};
```
## Rounded Corners
Prefer `borderRadius` for rect-like rounded corners:
```ts
slide.shapes.add({
geometry: "rect",
position: { left: 80, top: 120, width: 320, height: 160 },
fill: "white",
borderRadius: "rounded-2xl",
});
shape.borderRadius = 24;
```
Numbers are pixels. Strings use supported `rounded-*` tokens. `borderRadius`
requires a shape with width/height and is supported for `rect`, `textbox`, and
`roundRect`-like shapes. Use `adjustmentList` only when you need exact OpenXML
preset adjustment formulas.
## Rounded Rect Adjustment
```ts
const rounded = slide.shapes.add({
geometry: "roundRect",
position,
fill,
line,
adjustmentList: [{ name: "adj", formula: adjustmentFormula }],
});
rounded.adjustmentList = [{ name: "adj", formula: nextAdjustmentFormula }];
rounded.adjustmentList;
```
The `adj` value uses the OpenXML shape adjustment scale for the corner radius.
## Custom Path
```ts
const custom = slide.shapes.add({
geometry: "custom",
position,
fill,
line,
customPaths: [
{
width,
height,
commands,
},
],
});
custom.customPaths = nextCustomPaths;
custom.customPaths;
```
Custom path coordinates use pixels in the path viewport.
## Bézier Curve
```ts
const curve = slide.shapes.add({
geometry: "custom",
name: "Bezier curve",
position: { left: 120, top: 190, width: 720, height: 240 },
fill: "none",
line: { style: "solid", fill: "#2463EB", width: 3 },
customPaths: [{
width: 720,
height: 240,
commands: [
{ moveTo: { x: 0, y: 150 } },
{ cubicBezTo: { x1: 100, y1: 150, x2: 120, y2: 0, x: 240, y: 40 } },
{ cubicBezTo: { x1: 360, y1: 80, x2: 320, y2: 240, x: 480, y: 190 } },
{ cubicBezTo: { x1: 620, y1: 130, x2: 620, y2: 80, x: 720, y: 100 } },
],
}],
});
```
Each cubic starts at the previous endpoint; `(x1, y1)` and `(x2, y2)` are its
control points, and `(x, y)` is its endpoint. Omit `close` for an open curve.
These coordinates define the curve directly; `adjustmentList` is for named
geometry parameters. Use `slide.shapes.connect(..., { kind: "curved" })` for
a connector that follows attached shapes.
## Custom Path Inline Type
```ts
type CustomShapeConfig = Omit<PresetShapeConfig, "geometry"> & {
geometry: "custom";
customPaths: Array<{
id?: string;
width: number;
height: number;
commands: Array<
| { moveTo: { x: number; y: number } }
| { lineTo: { x: number; y: number } }
| { quadBezTo: { x1: number; y1: number; x: number; y: number } }
| { cubicBezTo: { x1: number; y1: number; x2: number; y2: number; x: number; y: number } }
| { close: Record<string, never> }
>;
}>;
};
```
## Connector
```ts
const connector = slide.shapes.connect(sourceShape, targetShape, {
kind: "elbow",
fromSide: "right",
toSide: "left",
line: { style: "solid", fill: "slate-400", width: 2 },
head: { type: "arrow", width: "med", length: "med" },
});
```
Use [`connectors.md`](./connectors.md) for connector routing, side anchors,
direct `geometry: "connector"` creation, arrowheads, and endpoint edits.
## Line Primitive Decision
| Need | Use |
| --- | --- |
| Divider inside compose JSX | `<rule stroke="slate-200" weight={1} />` |
| Free-positioned line | `slide.shapes.add({ geometry: "line", position, fill: "none", line })` |
| Freeform curve with Bézier control points | `slide.shapes.add({ geometry: "custom", position, fill: "none", line, customPaths })` |
| Arrow connected to shapes | `slide.shapes.connect(fromShape, toShape, { line, head })` |
| Border around a surface | shape or box `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
## Shadows
Supported shadow tokens:
```text
shadow-none, shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
```
Custom shadow strings are also supported when the presentation has a theme
context:
```ts
shape.shadow = "shadow-md";
shape.shadow = "2px 7px 19px #000000/17";
shape.shadow = "shadow-none";
```
## Ordering
```ts
shape.bringToFront();
shape.bringForward();
shape.sendToBack();
shape.sendBackward();
```
These inherited methods also apply to images, tables, charts, embedded workbooks, and SmartArt. Forward/backward moves one position in the owning surface’s stack; front/back moves to an end.
## Cookbook
```ts
// KPI metric surface.
const metricSurface = slide.shapes.add({
geometry: "roundRect",
name: "kpi-surface",
position: { left: 64, top: 132, width: 260, height: 148 },
fill: "white",
line: { style: "solid", fill: "slate-200", width: 1 },
borderRadius: "rounded-2xl",
shadow: "shadow-md",
});
metricSurface.text = "Revenue\n$12.4M";
metricSurface.text.style = {
className: "text-slate-950 text-2xl font-bold leading-tight",
};
```
```ts
// Pill label.
const pill = slide.shapes.add({
geometry: "roundRect",
position: { left: 64, top: 64, width: 148, height: 34 },
fill: "emerald-50",
line: { style: "solid", fill: "emerald-200", width: 1 },
borderRadius: "rounded-full",
});
pill.text = "ON TRACK";
pill.text.style = { className: "text-emerald-800 text-sm font-bold" };
```
```ts
// Directional connector between two shapes.
slide.shapes.connect(sourceShape, targetShape, {
kind: "elbow",
fromSide: "right",
toSide: "left",
line: { style: "solid", fill: "slate-400", width: 2 },
head: { type: "triangle", width: "sm", length: "sm" },
});
```
@@ -0,0 +1,199 @@
# Slide Facade
## Slide Show Visibility
```ts
slide.hidden = isHidden;
```
Hidden slides stay in the deck but are skipped during a slide show.
## Content Collections
```ts
const shape = slide.shapes.add(shapeConfig);
const image = slide.images.add(imageConfig);
const table = slide.tables.add(tableConfig);
const chart = slide.charts.add(chartType, chartConfig);
```
## Content Config Pointers
```ts
type ShapeConfig = PresetShapeConfig | CustomShapeConfig | ConnectorConfig; // see shapes.spec.md
type ImageConfig = ImageAddOptions; // see images.spec.md
type TableConfig = TableAddOptions | TableCellValue[][]; // see tables.spec.md
type ChartConfig = {
position?: { left?: number; top?: number; width?: number; height?: number };
title?: string;
categories?: string[];
series?: Array<{ name: string; values?: number[] }>;
}; // see charts.spec.md for axes, legend, labels, and series styling
```
## Background
```ts
const slide = presentation.slides.add({ background: { fill: fillConfig } });
slide.background.fill = fillConfig;
```
`fillConfig` accepts theme color strings, hex strings, solid configs, gradient configs, pattern configs, and image-fill configs.
## Layouts And Placeholders
```ts
slide.setLayout(layout);
const placeholder = slide.placeholders.getItem(placeholderName);
placeholder.text = placeholderText;
placeholder.text.style = placeholderStyleName;
```
```ts
const actualPlaceholders = slide.placeholders.items;
const emptyContentPlaceholders = slide.placeholders.editable;
const allVisibleEmptyPlaceholders = slide.placeholders.unfilled;
const missingLayoutSlots = slide.placeholders.availableFromLayout;
const createdPlaceholders = slide.placeholders.addFromLayout();
```
## Frame And Export
```ts
const frame = slide.frame;
const preview = await slide.export({ format, scale });
const pdf = await slide.export({ format: "pdf" });
```
## Compose Layout
```tsx
/** @jsxRuntime automatic */
slide.compose(
<row width="fill" height="fill" gap={20}>
<column width={340} height="fill" gap={12}>
<paragraph name="summary" className="text-slate-950 text-3xl font-bold">
Summary
</paragraph>
<paragraph className="text-slate-600 text-sm">
Compose-first layouts stay readable and export cleanly.
</paragraph>
</column>
<box name="surface" width="fill" height="fill" padding={16} fill="#ffffff">
<column height="fill" gap={10}>
<rule stroke="#0f172a" weight={2} />
</column>
</box>
</row>,
{
frame: { left: 48, top: 40, width: 864, height: 460 },
baseUnit: 8,
},
);
```
`slide.compose(...)` accepts either compose helper nodes or a JSX-authored tree.
It still returns the materialized elements. Use `name` on materializing nodes
when the slide needs stable inspect or layout-export anchors.
## Export Inline Type
```ts
type SlideExportOptions = {
format?: "png" | "jpeg" | "webp" | "pdf" | "layout";
width?: number;
height?: number;
scale?: number;
quality?: number;
};
```
`format: "layout"` exports the composed layout tree alongside the materialized slide elements. That is the most useful export when you need stable names, hierarchy paths, and resolved text for follow-up targeting.
## Auto Layout
```ts
slide.autoLayout(shapes, {
direction,
frame,
align,
horizontalGap,
verticalGap,
horizontalPadding,
verticalPadding,
});
```
## Auto Layout Inline Type
```ts
type AutoLayoutOptions = {
direction?: "horizontal" | "vertical";
frame?:
| "slide"
| Shape
| { left: number; top: number; width: number; height: number };
align?:
| "center"
| "topLeft"
| "topCenter"
| "topRight"
| "left"
| "right"
| "bottomLeft"
| "bottomCenter"
| "bottomRight";
horizontalGap?: number | "auto";
verticalGap?: number | "auto";
horizontalPadding?: number;
verticalPadding?: number;
};
```
## Speaker Notes
```ts
slide.speakerNotes.text = notesText;
slide.speakerNotes.setVisible(visible);
```
## Visual QA Loop
```ts
const preview = await slide.export({ format: "png", scale: 2 });
const layout = await slide.export({ format: "layout" });
const after = await presentation.inspect({
kind: "slide,textbox,shape,image,table,chart,notes",
target: { id: slideAnchorId, beforeLines: 2, afterLines: 8 },
maxChars: 4000,
});
```
Check the PNG for clipping, overlap, weak contrast, illegible text, bad image
crops, accidental rasterized labels, and off-canvas elements. Check the layout
export or inspect output for stable `name` values on important nodes.
## Cookbook
```ts
// Gradient background plus editable content.
slide.background.fill = "linear(180deg, slate-950 0%, blue-950 100%)";
const title = slide.shapes.add({
geometry: "textbox",
name: "title",
position: { left: 72, top: 72, width: 760, height: 120 },
fill: "none",
line: { style: "solid", fill: "none", width: 0 },
});
title.text = "Editable headline";
title.text.style = { fontSize: 44, bold: true, color: "white" };
```
```ts
// Clone rhythm from another slide, then change content.
const next = sourceSlide.duplicate();
next.moveTo(3);
next.placeholders.getItem("title").text = "Updated section title";
```
@@ -0,0 +1,48 @@
# Speaker Notes
Speaker notes live on `slide.speakerNotes`.
## Set Text
```ts
const speakerNotes = slide.speakerNotes;
speakerNotes.text = notesText;
const savedText = speakerNotes.text;
```
## Notes Text Inline Type
```ts
type NotesTextValue = string | string[] | StructuredTextInput;
type TextRunInput = {
run: string;
style?: { bold?: boolean; italic?: boolean; fontSize?: string; color?: FillConfig };
textStyle?: TextRunInput["style"]; // Compatibility alias.
};
```
## Visibility And Clearing
```ts
speakerNotes.setVisible(visible);
const visibleState = speakerNotes.isVisible();
speakerNotes.clear();
```
## Cookbook
```ts
// Structured presenter notes.
slide.speakerNotes.text = [
"Open with the customer problem, not the feature list.",
"Call out the chart source before discussing the slope.",
"Pause for questions before the implementation timeline.",
];
slide.speakerNotes.setVisible(true);
```
```ts
// Append without deleting imported notes.
slide.speakerNotes.append("\nFollow-up: confirm launch date with PM.");
```
@@ -0,0 +1,85 @@
# Named Text Styles
`presentation.styles` stores reusable text styles for shapes and text ranges.
## Style Surface Map
| Need | API |
| --- | --- |
| Deck-level tokenized text style ids | `presentation.theme.textStyles({...})` |
| Slide-scoped generated text style ids | `slide.theme.textStyles({...})` |
| Explicit named styles by facade | `presentation.styles.add(name)` |
## Built-In Styles
```ts
const styles = presentation.styles;
const style = styles.get(styleName);
const summary = styles.describe(styleName);
const allStyles = styles.describe();
```
## Custom Style
```ts
const custom = presentation.styles.add(styleName);
custom.description = styleDescription;
custom.color = styleColor;
custom.bold = isBold;
custom.italic = isItalic;
custom.fontSize = fontSizePx;
custom.alignment = alignment;
```
## Named Style Facade Fields
```ts
type NamedStyleFacade = {
description?: string;
usageHint?: string;
bold?: boolean;
italic?: boolean;
fontSize?: number;
alignment?: "left" | "center" | "right" | "justify";
underline?: string;
color?: ColorConfig;
};
```
Use broader `TextStyleConfig` objects on `shape.text.style = { ... }`,
`presentation.theme.textStyles(...)`, and `slide.theme.textStyles(...)`.
## Use A Style
```ts
shape.text = textValue;
shape.text.style = styleName;
const range = shape.text.get(rangeText);
range.style = styleName;
```
Named styles are block-level for paragraph style assignments and range-level for selected text ranges.
## Cookbook
```ts
// Deck-level type scale.
const display = presentation.styles.add("Display");
display.fontSize = 52;
display.bold = true;
display.color = "#0f172a";
display.usageHint = "Hero and section titles";
const body = presentation.styles.add("Body");
body.fontSize = 20;
body.color = "#475569";
body.usageHint = "Readable body copy";
```
```ts
// Apply a style, then emphasize one range.
shape.text = "Revenue accelerated across enterprise accounts.";
shape.text.style = "Body";
shape.text.get("Revenue").style = "Display";
```
@@ -0,0 +1,198 @@
# Tables
`slide.tables` creates and edits PowerPoint-style tables.
## Resolved From Inspect
```ts
const table = presentation.resolve("tb/d4e5f6a7");
table.cells.set(1, 2, "$4.2M");
table.getCell(1, 2).text.style = "Body Small";
table.borders.assign({ style: "solid", fill: "slate-200", width: 1 });
```
Use `presentation.inspect({ kind: "table", search })` to find the `tb/...`
anchor id. If an imported table resolves as an image, preserve it as an image or
rebuild it as a native table intentionally.
## Add Table
```ts
const table = slide.tables.add({
rows,
columns,
left,
top,
width,
height,
columnTracks: [fr(2), fr(1), fixed(120)],
values,
});
```
Primitive matrices and structured text runs are accepted for `values`. Use `columnTracks` with `fr(...)` and `fixed(...)` when a table should fill its frame with proportional columns. Use `columnWidths` only for explicit pixel widths.
## Table Inline Types
```ts
type TableAddOptions = {
rows: number;
columns: number;
left?: number;
top?: number;
width?: number;
height?: number;
values?: TableCellValue[][];
columnTracks?: TableColumnTrack[];
columnWidths?: number[];
};
type TableColumnTrack =
| { mode: "fr"; value: number }
| { mode: "fixed"; value: number };
type TableCellValue = string | number | string[] | StructuredTextInput | Text;
```
## Cells
```ts
const cell = table.getCell(rowIndex, columnIndex);
cell.value = cellValue;
cell.fill = fillConfig;
cell.text.style = textStyleName;
table.cells.set(rowIndex, columnIndex, textObjectOrValue);
```
## Ranges And Merges
```ts
table.merge({
startRow,
endRow,
startColumn,
endColumn,
});
const range = table.cells.block(rangeConfig);
range.fill = fillConfig;
range.textStyle.bold = isBold;
range.textStyle.color = textColor;
range.textStyle.fontSize = fontSizePx;
range.borders = borderConfig;
table.unmerge({ startRow, endRow, startColumn, endColumn });
```
## Insert And Delete Rows Or Columns
```ts
table.insertRows({ index: rowIndex, count: 2 });
table.deleteRows({ index: rowIndex, count: 1 });
table.insertColumns({ index: columnIndex });
table.deleteColumns({ index: columnIndex });
```
## Range And Merge Inline Types
```ts
type TableMergeRange = {
startRow: number;
endRow: number;
startColumn: number;
endColumn: number;
};
type TableCellRangeConfig = {
row: number;
column: number;
rowCount: number;
columnCount: number;
};
```
## Style
```ts
table.style = tableStyleId;
table.styleOptions = tableStyleOptions;
table.columnTracks = [fr(2), fr(1), fixed(120)];
table.rows[0].height = headerHeightPx;
table.columns.get(columnIndex).width = columnWidthPx;
table.borders.assign(borderConfig);
table.cells.block({ row, column, rowCount, columnCount }).assign({
fill,
textStyle,
borders,
margins,
anchor,
horizontalOverflow,
});
```
## Style Inline Types
```ts
type TableStyleOptions = {
headerRow?: boolean;
totalRow?: boolean;
firstColumn?: boolean;
lastColumn?: boolean;
bandedRows?: boolean;
bandedColumns?: boolean;
};
type TableBorderLineConfig = {
style?: "solid" | "dashed" | "dotted" | "dash-dot" | "dash-dot-dot" | string;
width?: number;
fill?: FillConfig;
color?: FillConfig;
};
```
## Cookbook
```ts
// Compact KPI table.
const table = slide.tables.add({
rows: 4,
columns: 3,
left: 96,
top: 168,
width: 680,
height: 220,
values: [
["Metric", "Current", "Delta"],
["Revenue", "$12.4M", "+18%"],
["Retention", "94%", "+3 pts"],
["Latency", "182 ms", "-22 ms"],
],
});
table.styleOptions = { headerRow: true, bandedRows: true };
table.getCell(0, 0).fill = "slate-950";
table.getCell(0, 1).fill = "slate-950";
table.getCell(0, 2).fill = "slate-950";
table.borders.assign({ style: "solid", fill: "slate-200", width: 1 });
```
```ts
// Spanning title row.
table.merge({ startRow: 0, endRow: 0, startColumn: 0, endColumn: 2 });
table.getCell(0, 0).value = "Regional performance";
table.getCell(0, 0).text.style = "title";
```
```ts
// Highlight a cell range.
const riskRange = table.cells.block({
row: 2,
column: 2,
rowCount: 2,
columnCount: 1,
});
riskRange.fill = "amber-50";
riskRange.textStyle.color = "#92400e";
riskRange.textStyle.bold = true;
```
@@ -0,0 +1,97 @@
# Theme
Themes provide default fonts, named colors, and text style tokens.
## Default Font
```ts
presentation.theme.defaultFont = "Aptos";
```
New presentations default to Aptos. Set `defaultFont: string` once during setup
to choose the theme's Latin heading and body font. Shape text with no explicit
`typeface` inherits the theme; a local `typeface` overrides it. The choice persists with
the presentation. Imported presentations retain their existing font schemes;
changing `defaultFont` preserves language-specific font mappings.
## Color Scheme
```ts
presentation.theme.colorScheme = {
name: themeName,
themeColors,
};
const hexMap = presentation.theme.hexColorMap;
```
`themeColors` maps every theme color name to a color config value. Assigning
`presentation.theme.colorScheme` replaces the active scheme, so provide the
full map.
## Color Scheme Inline Type
```ts
type ThemeColorName =
| "accent1" | "accent2" | "accent3" | "accent4" | "accent5" | "accent6"
| "bg1" | "bg2" | "tx1" | "tx2" | "dk1" | "lt1" | "dk2" | "lt2"
| "hlink" | "folHlink";
type ColorSchemeConfig = {
name: string;
themeColors: Record<ThemeColorName, ColorConfig>;
};
```
## Theme Colors In Content
```ts
const shape = slide.shapes.add({
geometry,
position,
fill: themeColorName,
line: { style: lineStyle, fill: lineColor, width: lineWidthPx },
});
```
## Text Styles
```ts
const styles = slide.theme.textStyles({
[styleName]: textStyleConfig,
});
```
## Cookbook
```ts
// Business/product palette.
presentation.theme.colorScheme = {
name: "Product Editorial",
themeColors: {
accent1: "#2563eb",
accent2: "#0f766e",
accent3: "#f59e0b",
accent4: "#dc2626",
accent5: "#7c3aed",
accent6: "#16a34a",
bg1: "#ffffff",
bg2: "#f8fafc",
tx1: "#0f172a",
tx2: "#475569",
dk1: "#000000",
dk2: "#1e293b",
lt1: "#ffffff",
lt2: "#e2e8f0",
hlink: "#2563eb",
folHlink: "#7c3aed",
},
};
```
```ts
// Use theme tokens in content so later theme changes flow through.
slide.background.fill = "bg1";
shape.fill = "accent1";
shape.text.style = { color: "tx1" };
```
@@ -0,0 +1,447 @@
# Presentation Token Reference
This reference covers the Tailwind-like tokens supported by presentation
shapes, text, and JSX. These are presentation tokens, not browser CSS.
## Where Tokens Work
| Surface | Token entry |
| --- | --- |
| Shape/box fill | `fill="sky-500"`, `fill="rose-500/80"` |
| Shape/box line | `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
| Shape/box radius | `borderRadius="rounded-xl"` |
| Image radius | `borderRadius="rounded-2xl"` |
| Shape shadow | `shadow="shadow-md"` |
| Shape/box className | `className="bg-white rounded-xl shadow-sm"` |
| Text className | `className="text-slate-700 text-lg font-bold leading-tight"` |
| Imperative shape | `shape.className = "bg-sky-50 rounded-lg shadow"` |
| Imperative text | `shape.text.style = { className: "text-slate-800 text-xl leading-relaxed" }` |
| Text range | `shape.text.get("Total").className = "text-emerald-600 font-bold"` |
Explicit props override `className` on JSX nodes. For example,
`<box className="bg-slate-900" fill="white" />` uses the explicit `fill`.
`className` is only for visual/text tokens. Use real JSX props for layout:
`width`, `height`, `gap`, `padding`, `align`, and `justify`.
## Decision Table
| Need | Use |
| --- | --- |
| Common shape styling | `className="bg-white rounded-xl shadow-sm"` |
| Exact fill or gradient | `fill="#0f172a"` or `fill="linear(135deg, #fff 0%, sky-100 100%)"` |
| Exact line | `line={{ style: "solid", fill: "slate-200", width: 1 }}` |
| Common text styling | `className="text-slate-700 text-lg font-bold leading-tight"` |
| Exact text style | `style="font: 700 22px Inter; color: #334155; leading: 1.25; wrap: none"` |
| Inline emphasis | `<run textStyle={{ bold: true, color: "sky-600" }}>...</run>` |
| Layout | real props such as `gap={24}`, `padding={{ x: 32, y: 24 }}`, `align="center"` |
## Token Cookbook
Transparent overlay:
```tsx
<shape geometry="rect" width="fill" height="fill" fill="black/45" />
<paragraph className="text-white/80 text-xl">Readable over an image</paragraph>
```
Theme color with a transform:
```tsx
<box fill="accent1+18/90" />
<paragraph style="font: 700 18px Inter; color: tx1-10/85; wrap: none">
Theme-aware text
</paragraph>
```
`+` lightens, `-` darkens, and `/` sets opacity. The suffix accepts unit
fractions, numbers, or percentages: `accent1+0.18/0.9`, `accent1+18/90`, and
`accent1+18%/90%` are equivalent.
Soft surface with exact line:
```tsx
<box
fill="slate-50"
line={{ style: "solid", fill: "slate-200", width: 1 }}
borderRadius="rounded-2xl"
shadow="shadow-sm"
/>
```
No fill, visible stroke:
```tsx
<shape
geometry="ellipse"
fill="none"
line={{ style: "dashed", fill: "sky-500/70", width: 2 }}
width={96}
height={96}
/>
```
Gradient background plus transparent edge:
```tsx
<box fill="linear(135deg, #ffffff 0%, sky-100 58%, #ffffff/0 100%)" />
```
Radial highlight:
```tsx
<shape
geometry="ellipse"
fill="radial(white/80 0%, emerald-200/45 48%, emerald-700/0 100%)"
width={420}
height={260}
/>
```
Custom shadow:
```tsx
<box fill="white" borderRadius="rounded-2xl" shadow="2px 7px 19px #000000/17" />
```
Exact text style string:
```tsx
<paragraph style="font: 700 24px Inter; color: #334155; leading: 1.2; wrap: none">
One-line label
</paragraph>
```
Tokenized text with arbitrary size and leading:
```tsx
<paragraph className="text-slate-950 text-[32px] font-bold leading-[1.12]">
Precise headline
</paragraph>
```
## Color Tokens
Color tokens can be used directly as fill/color strings or through `bg-*` and
`text-*` class names.
```tsx
<box fill="slate-950" line={{ style: "solid", fill: "slate-700", width: 1 }} />
<box className="bg-sky-50 rounded-xl shadow-sm" />
<paragraph className="text-slate-700 text-lg">Readable text</paragraph>
```
Alpha suffixes are supported:
```tsx
<shape geometry="rect" fill="black/45" width="fill" height="fill" />
<paragraph className="text-white/80 text-xl">Muted overlay text</paragraph>
<box className="bg-rose-500/75 rounded-full" />
```
Theme colors and aliases are supported as color strings:
```tsx
<box fill="accent1" />
<box fill="accent2+20/80" />
<paragraph style="font: 600 18px Inter; color: text1/80; wrap: none">
Uses the presentation theme text color
</paragraph>
```
Theme names:
```text
accent1, accent2, accent3, accent4, accent5, accent6,
bg1, bg2, tx1, tx2, dk1, dk2, lt1, lt2, hlink, folHlink
```
Aliases:
```text
background1 -> bg1
background2 -> bg2
text1 -> tx1
text2 -> tx2
dark1 -> dk1
dark2 -> dk2
light1 -> lt1
light2 -> lt2
```
Supported color names:
| Family | Tokens |
| --- | --- |
| Neutrals | `slate`, `gray`, `zinc`, `neutral`, `stone` |
| Warm | `red`, `orange`, `amber`, `yellow`, `lime` |
| Green/blue | `green`, `emerald`, `teal`, `cyan`, `sky`, `blue` |
| Violet/pink | `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose` |
| Additional muted sets | `mauve`, `mist`, `olive`, `taupe` |
| Singletons | `black`, `white` |
For palette families, supported shades are:
```text
50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950
```
Use `family-shade`, for example `slate-50`, `slate-900`, `sky-500`,
`emerald-700`, or `rose-950`.
Alpha values accept percent-like numbers, percentages, or unit fractions:
```text
sky-500/80
sky-500/80%
sky-500/0.8
black/10
white/65
```
Hex, short hex, RGB, RGBA, and `transparent` are accepted:
```tsx
<box fill="#0F172A/12" />
<box fill="#0F172A1F" />
<box fill="rgb(15 23 42 / 12%)" />
<box fill="rgba(15, 23, 42, 0.12)" />
<shape geometry="rect" fill="transparent" />
```
Use `fill="none"` when the object should have no fill. Use
`fill="transparent"` or `#00000000` when the object should keep an editable
transparent solid fill. Express transparent and no-fill cases with the explicit
`fill` prop.
## Gradient Strings
Gradient fill strings are supported wherever `FillConfig` strings are accepted.
Use them for editable vector backgrounds and surfaces:
```tsx
<box fill="linear(135deg, #ffffff 0%, sky-100 55%, #ffffff/0 100%)" />
<shape geometry="ellipse" fill="radial(#ffffff 0%, emerald-200 48%, emerald-700 100%)" />
```
`linear(...)` accepts an optional angle first. `radial(...)` is a path gradient.
Stops use color plus optional offset percentages.
Offsets are optional; when omitted, stops are distributed evenly:
```tsx
<box fill="linear(slate-950, blue-800, sky-400)" />
```
Use explicit offsets when a narrow band or fade matters:
```tsx
<box fill="linear(90deg, black/80 0%, black/36 42%, black/0 100%)" />
<shape geometry="ellipse" fill="radial(accent1+35/55 0%, accent1/12 58%, accent1/0 100%)" />
```
## Shape Class Tokens
Shape and box `className` supports:
```text
bg-*
rounded
rounded-none
rounded-sm
rounded-md
rounded-lg
rounded-xl
rounded-2xl
rounded-3xl
rounded-full
shadow-none
shadow-sm
shadow
shadow-md
shadow-lg
shadow-xl
shadow-2xl
```
Example:
```tsx
<box
width="fill"
height={180}
className="bg-white rounded-xl shadow-md"
line={{ style: "solid", fill: "slate-200", width: 1 }}
/>
```
Radius values:
| Token | Radius |
| --- | ---: |
| `rounded-none` | `0px` |
| `rounded-sm` | `2px` |
| `rounded` | `4px` |
| `rounded-md` | `6px` |
| `rounded-lg` | `8px` |
| `rounded-xl` | `12px` |
| `rounded-2xl` | `16px` |
| `rounded-3xl` | `24px` |
| `rounded-full` | `9999px` |
Shadow tokens:
```text
shadow-none, shadow-sm, shadow, shadow-md, shadow-lg, shadow-xl, shadow-2xl
```
Custom shadow strings are also supported on `shadow`:
```tsx
<box shadow="2px 7px 19px #000000/17" />
```
## Text Class Tokens
Text `className` supports color, size, weight, italic, and leading:
```tsx
<paragraph className="text-slate-950 text-5xl font-bold leading-tight">
Large headline
</paragraph>
<paragraph className="text-slate-600 text-lg leading-relaxed">
Body copy with looser line spacing.
</paragraph>
```
Text sizes:
| Token | Size |
| --- | ---: |
| `text-xs` | `12px` |
| `text-sm` | `14px` |
| `text-base` | `16px` |
| `text-lg` | `18px` |
| `text-xl` | `20px` |
| `text-2xl` | `24px` |
| `text-3xl` | `30px` |
| `text-4xl` | `36px` |
| `text-5xl` | `48px` |
| `text-6xl` | `60px` |
| `text-[32px]` | arbitrary positive pixel size |
Font weight tokens:
| Bold flag | Tokens |
| --- | --- |
| `true` | `font-semibold`, `font-bold`, `font-black` |
| `false` | `font-thin`, `font-extralight`, `font-light`, `font-normal`, `font-medium`, `font-extrabold` |
Font weight maps to a boolean bold flag, not numeric weights. Use only
`font-semibold`, `font-bold`, or `font-black` when the text should be bold. Use
`font-normal` when the text should not be bold. `font-extrabold` maps to the
non-bold side because exact `500`/`600`/`700`/`800` differences are not
preserved.
`italic` sets italic text.
Leading tokens:
| Token | Line spacing |
| --- | ---: |
| `leading-none` | `1` |
| `leading-tight` | `1.25` |
| `leading-snug` | `1.375` |
| `leading-normal` | `1.5` |
| `leading-relaxed` | `1.625` |
| `leading-loose` | `2` |
| `leading-3` through `leading-10` | `12px` through `40px`, converted against current font size |
| `leading-[1.35]` | arbitrary multiplier |
| `leading-[150%]` | percentage multiplier |
| `leading-[28px]` | absolute pixels, converted against current font size |
When using absolute leading such as `leading-7` or `leading-[28px]`, put the
text size token before the leading token in the class string so conversion uses
the intended font size:
```tsx
<paragraph className="text-2xl leading-8">24px text with 32px leading</paragraph>
```
## Direct Props Versus Class Names
Use direct props when a value is part of the object schema:
```tsx
<shape
geometry="rect"
fill="emerald-500"
line={{ style: "solid", fill: "emerald-700", width: 1 }}
borderRadius="rounded-lg"
shadow="shadow-sm"
width={160}
height={96}
/>
```
Use `className` when grouping common style tokens:
```tsx
<box className="bg-emerald-50 rounded-xl shadow-sm">
<paragraph className="text-emerald-900 text-xl font-bold leading-tight">
Compact token styling
</paragraph>
</box>
```
Use object `style` for exact text settings that tokens do not cover:
```tsx
<paragraph
style={{
typeface: "Aptos",
fontSize: 22,
color: "slate-700",
alignment: "center",
lineSpacing: 1.2,
}}
>
Exact text config
</paragraph>
```
Use a compact style string when the exact settings fit on one line:
```tsx
<paragraph style="font: italic 600 20px Aptos; color: slate-700; leading: 1.25; align: center">
Compact exact text config
</paragraph>
```
Supported text style declarations:
```text
font, size, font-size, family, font-family, typeface,
weight, font-weight, italic, font-style, color, fill,
leading, align, alignment, wrap, underline, inset, insets,
padding, autofit, auto-fit
```
Use `leading`, not `line-height`, in style strings.
## ClassName Scope
The token parser covers visual and text styling. JSX layout props represent
layout utilities such as padding, gap, width, height, flex flow, grid flow,
alignment, and distribution:
```tsx
<row width="fill" height="fill" gap={24} align="center" justify="between" />
<box padding={{ x: 32, y: 24 }} line={{ style: "solid", fill: "slate-200", width: 1 }} />
```
## Source References
- `src/models/presentation/utils/tailwind/*.ts`: token parsers.
- `src/models/presentation/utils/tailwind/tailwind-colors.generated.ts`: full
color token map.
- `tests/presentation/tailwind-tokens.sanity.spec.ts`: visual token coverage.