# SDK: Slides

> A deck is PowerPoint's model, made by code with python-pptx's API: a module listed in allyhub.yaml as kind: slides (project.md), and the two files it names in presentation({ slides, script }), each from the module's folder:

Source: https://allyhub.com/docs/reference/sdk/slides · AllyHub 0.10.0
Index of all docs: https://allyhub.com/llms.txt

- its module (`deck.ts`): the presentation's slide masters, layouts and placeholders, components and generators.
- its slides file (`slides: "./deck.yaml"`): the slides in order, each on a layout, and what a person (or you) placed or changed on a slide. A value there overrides the layout's, as a placeholder moved on a slide does in PowerPoint.
- its script (`script: "./deck.{locale}.yaml"`): each slide's words, by shape name, and its speaker notes, a file per language: `{locale}` once in the file's name stands for each (`deck.en.yaml`, `deck.zh-cn.yaml`).

A deck that names no slides file or no script is AK-M011. Two decks in one folder share a file only when both name it.

The API is python-pptx 1.0.2's, by its names and behaviour; its documentation (python-pptx.readthedocs.io) is the reference. `allyhub slides capabilities` lists which of its classes, names and enumerations are held, where they differ, and what is added. A name that is not held throws where it is written, naming what its class holds. This page is what is AllyHub's own.

```ts file=launch/deck/deck.ts
  Inches,
  MSO_ANCHOR,
  PP_PLACEHOLDER,
  Pt,
  presentation,
} from "@allyhub/sdk/slides";

  { slides: "./deck.yaml", script: "./deck.{locale}.yaml", size: "16:9" },
  (prs) => {
    prs.theme.colors = { accent1: "#2F5BEA" };
    const master = prs.slide_masters.add("Brand");
    const title = master.placeholders.add(
      PP_PLACEHOLDER.TITLE,
      Inches(0.6),
      Inches(0.4),
      Inches(12),
      Inches(1.2),
    );
    title.text_frame.vertical_anchor = MSO_ANCHOR.MIDDLE;
    title.text_frame.list_style[0].font.size = Pt(40);
    master.placeholders.add(
      PP_PLACEHOLDER.BODY,
      Inches(0.6),
      Inches(1.8),
      Inches(12),
      Inches(5),
    );
    master.shapes.add_picture(
      "../../../assets/media/logo.png",
      Inches(12.2),
      Inches(6.9),
      Inches(0.9),
      Inches(0.4),
    ).name = "logo";

    const cover = master.slide_layouts.add("Title Slide");
    cover.placeholders.add(
      PP_PLACEHOLDER.CENTER_TITLE,
      Inches(1),
      Inches(2.5),
      Inches(11.3),
      Inches(1.5),
    );
    cover.placeholders.add(PP_PLACEHOLDER.SUBTITLE);

    const content = master.slide_layouts.add("Title and Content");
    content.placeholders.add(PP_PLACEHOLDER.TITLE);
    content.placeholders.add(PP_PLACEHOLDER.BODY);
  },
);
```

```yaml
# launch/deck/deck.yaml
slides:
  - id: cover
    layout: Title Slide
  - id: how
    layout: Title and Content
    shapes:
      hero:
        { picture: ./media/hero.png, frame: { x: 560, y: 120, w: 360, h: 300 } }
      title: { text: { size: 44 } }
```

```yaml
# launch/deck/deck.en.yaml
title: Launch deck
slides:
  - id: cover
    text: { title: Tidyform, subtitle: Contracts, read for you }
    notes: Thank the partners first.
  - id: how
    text:
      title: How it works
      body: [Drop a file, It is read, You sign]
```

## `presentation()`

`presentation(options, (prs) => { … })` is the default export of a deck's module; its function is given python-pptx's `Presentation` and makes the deck's masters, layouts, components and generators. Paths are from the module's folder; lengths are EMU (`Inches`, `Pt`, `Cm`, `Mm`, `Emu`), each python-pptx's Length: a number that also says itself in `.emu`, `.inches`, `.cm`, `.mm`, `.pt`, `.centipoints` and `.twips`, as what a length reads does (`shape.width.inches`). Arithmetic on Lengths gives a plain number; two Lengths of one value are `===`, and one is compared with a plain number by its `.emu`.

| Option  | Default            | What it is                                                                                                                                                                                                                            |
| ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `slides` | none | Its slides file (YAML), from the module's folder: the slides in order and what was placed or changed on each. Paths in it are from the module's folder too |
| `script` | none | Its script, from the module's folder, with `{locale}` once in its name for each language (`./deck.{locale}.yaml`) |
| `size`  | `"16:9"`           | A slide size by name (`16:9`, `16:10`, `4:3` as PowerPoint's; `a4`, `a4-portrait`, `letter`, `letter-portrait` the paper's own; a carousel is an image, [image.md](https://allyhub.com/docs/reference/sdk/image.md)) or `{ width, height }` in EMU                                                   |
| `title` | none | Its name for people, what lists show it by |
| `theme` | the project's look's colours, standard fonts | `{ colors, fonts }`: theme colours by PresentationML's names (`dk1`, `lt1`, `dk2`, `lt2`, `accent1`…`accent6`, `hlink`, `folHlink`), over the project's look (`dk1` its foreground, `lt1` its background, `accent1` its accent); fonts (`major`, `minor`, `major_east_asian`, `minor_east_asian`, and `code`, Courier New unless set, which the script's `` `code` `` is set in: PowerPoint's theme has no such font, so in the file it is a run's own), Arial and Microsoft YaHei unless set: fonts every PowerPoint, Keynote and Google Slides has. These and Calibri, Times New Roman, Cambria and Courier New are drawn here by fonts of the same metrics (Arimo, Noto Sans SC, Carlito, Tinos, Caladea, Cousine), so a line breaks in the file where it breaks here. Any other font the config's `fonts` lists goes in the PowerPoint file, a face each for regular, bold, italic and bold italic, unless its own licence bits (`fsType`) forbid it or it is a variable font; `allyhub render` says what did not go in. An app that does not read a file's fonts replaces them, and its lines may break elsewhere. A font named with no file the stage has is AK-L006 |

## Masters, layouts and placeholders

python-pptx opens these from a template; here code makes them.

- `prs.slide_masters.add(name)`: a master, with PowerPoint's Office text styles (`master.text_styles.title_style`, `body_style`, `other_style`, nine levels each) and no placeholders yet.
- `master.slide_layouts.add(name)`: a layout; its name is what the slides file's slides name, unique in the deck.
- `placeholders.add(PP_PLACEHOLDER.X, left, top, width, height, { name })` on a master or a layout. A layout's placeholder given no frame takes its master's of its base type, as python-pptx reads it (a centre title the title's, a subtitle, picture, media or object the body's). Its name is its type's (`title`, `subtitle`, `body`, `picture`, `content`…) unless given: the slides file and the script name it. Its idx is PowerPoint's: a title 0, a date, footer and slide number 10, 11 and 12, the rest from 1.
- Beyond python-pptx's `add_shape` and `add_connector` (`MSO_CONNECTOR.STRAIGHT`, `ELBOW`, `CURVE`, or a connector's preset by name, `straightConnector1`, `bentConnector2` to `5`, `curvedConnector2` to `5`; an elbow's middle is its `adjustments[0]`; `begin_connect(shape, site)` and `end_connect` glue its ends to a shape of the same slide, layout or master, at a site of the shape's geometry, numbered as its preset's `cxnLst` in ECMA-376 (most count counter-clockwise from the top: a rectangle's, a rounded rectangle's, a diamond's and a freeform's 0 top, 1 left, 2 bottom, 3 right; an ellipse's eight 0 top, 2 left, 4 bottom, 6 right; a hexagon's six start at its right), and its ends then follow the shape; `begin_x`, `begin_y`, `end_x` and `end_y` read and move them), `shapes.build_freeform(start_x, start_y, scale)` draws an outline in local units, `scale` EMU each, its start and every point after in those units (with `scale` 1 they are EMU) (`add_line_segments(vertices, close)`, which closes the outline back to its start unless `close` is `false`, as python-pptx's; `move_to`, `convert_to_shape`, and `add_curve_segment(x1, y1, x2, y2, x, y)`, a cubic curve python-pptx lacks), filled by its style as PowerPoint fills it, an open one too: `fill.background()` leaves a line; `line.dash_style` takes `MSO_LINE`, and `line.begin_arrow` and `end_arrow` take `MSO_ARROWHEAD`, each head's size `line.begin_arrow_width`, `begin_arrow_length`, `end_arrow_width` and `end_arrow_length` `MSO_ARROWHEAD_SIZE` (`SMALL`, `MEDIUM`, `LARGE`: two, three and five times the line's width, never less than 0.7 mm's; a freeform's open ends take heads too); `shapes.add_group_shape()` groups what is added to its `.shapes`, and a group is its shapes, listed and drawn as they are, holding no group; `shapes.add_table(rows, cols, left, top, width, height).table` has `cell(r, c)` with `text`, `text_frame`, `fill`, `borders` (`{ bottom: { color, width } }`), `merge`, margins and `vertical_anchor`. `layout.display_master_shapes = false` hides its master's shapes.
- A placeholder shrinks its text to fit its frame unless told not to (`MSO_AUTO_SIZE.TEXT_TO_FIT_SHAPE`, as PowerPoint's Office master's do; `text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps its sizes), and the type in use shows what it shrank to. A text box `add_textbox` makes does not wrap and grows to its text, as python-pptx's, so its frame has no room for its `vertical_anchor` to move it (`text_frame.auto_size = MSO_AUTO_SIZE.NONE` keeps the frame it was given); a shape `add_shape` makes starts with one centred paragraph, its text light 1 (white, on its accent 1 fill) by its style as PowerPoint's (a run's `font.color` sets its own), and `text_frame.text` replaces it with paragraphs aligned as the text style says (left), as python-pptx's.
- A run's `font.baseline` raises it by a share of its size (`0.3`, a superscript) or, below 0, lowers it (`-0.25`, a subscript): PowerPoint's `baseline`, which python-pptx has no name for.
- `shape.adjustments[i]` is the file's value over 100,000, as python-pptx's: most are a share of the shape's shorter side (`roundRect`'s `[0.16667]`); an angle's is in 60,000ths of a degree, so 0.6 a degree (`blockArc`'s first, 108, is 180°, measured clockwise from 3 o'clock). Reading `adjustments` gives a preset's defaults, each in its own scale.
- A colour in code is python-pptx's `ColorFormat`: `shape.fill.solid()` then `shape.fill.fore_color.rgb = RGBColor.from_string("1F4E79")` (or `"#1F4E79"`), `.theme_color = MSO_THEME_COLOR.ACCENT_1`, and the same on `line.color` and a run's `font.color`; a gradient's stops are each `color` and `position`, or set whole as `fill.gradient_stops = [{ at, color }, …]`.
- A shape is named by its kind and a number (`shape-3`) unless code names it; two shapes of one slide by one name are AK-M011, as the slides file and the script find a shape by its name.
- A text style is a list style's level, `ListLevel`: `alignment`, `line_spacing`, `space_before`, `space_after`, `font` (with `font.spacing`, the space between letters, a length, negative to tighten, which python-pptx has no name for), `bullet` (a character, or `null` for none), `bullet_font`, `margin_left`, `indent`. No bullet keeps the level's `margin_left` and `indent`, as PowerPoint's `a:buNone` does: Office's body levels hang their wrapped lines a quarter inch in, so text with no bullets sets both to `0` to stand flush. A placeholder's `text_frame.list_style[n]` is what the text a slide gives it takes at level n, over its master's placeholder and its master's text style for its type.

## Components

`prs.components.add(name, { props, layers })` is a shape drawn by code: `layers(props, { width, height, slide })` returns layers of the layer contract ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md): `custom()`, a component), laid out in the shape's frame; `width` and `height` are the frame's size in the slide's pixels (a 16:9 slide is drawn 1920 × 1080, 2 px a point). Its `render(t)` is given seconds into the slide; a still of the slide is drawn when what moves has settled. Its colours and fonts follow the deck's theme by the CSS variables the slide sets: `var(--ak-theme-<colour>)` for each theme colour (`--ak-theme-dk1`, `--ak-theme-lt1`, `--ak-theme-accent1`…`--ak-theme-folHlink`), `var(--ak-theme-major)` and `var(--ak-theme-minor)` for its fonts (`--ak-theme-major-ea`, `--ak-theme-minor-ea` for East Asian text). The look's `var(--ak-color-*)` and `var(--ak-font-*)` are the project's, which the theme starts from but does not follow once `prs.theme` sets its own. `props` lists the props a person may change in the editor, by the prop types (`text()`, `number()`…); the slides file places it as `{ component: name, props, frame }`, or code with `shapes.add_component(name, left, top, width, height, props)`. It moves for 4 seconds from when it comes on (`SLIDE_SECONDS`) unless its `dur` says how long, in seconds (`{ component: name, dur: 15 }`, or `add_component`'s last argument, `{ dur: 15 }`): its step rests no sooner, its still is drawn once it has, and a PowerPoint file's video of it is that long. `add` also takes what `defineComponent` makes ([layers.md](https://allyhub.com/docs/reference/sdk/layers.md#layers-in-a-frame)). A shape may name a component by its module instead, without registering it: `component: ../../components/ui.ts#ShareDialog` (its path from the module's folder and its export; `#default` may be left out). A component shape's props are fields in the editor's Format inspector, a field per prop type; what a person types is written to `props` in the slides file as its type (a number, a list).

## Generators

`prs.generators.add(name, (g) => { … })` makes slides from data: `g.data(path)` reads a data file (CSV rows, YAML, JSON) from the module's folder; `g.slides.add_slide(layout, id)` adds a slide on a layout (an object, or a name) with its id in the block, and the slide is python-pptx's (`shapes.title`, `placeholders[idx]`, `shapes.add_*`, `notes_slide.notes_text_frame.text`). A generated slide's words are its code's (from its data), not the script's. The slides file places the block as `- id: stories, generate: name`; its slide is `stories/<id>`, hidden by `hidden: [<id>]`, and a shape on it is changed as `shapes: { <id>/<shape>: … }`.

A slide drawn whole by code, a diagram, is one generator's slide. The deck is then three files: its module, its slides file placing the generator's block, and its script, which still has its file (with `{locale}` in its name, one language or many), with no rows (`slides: []`):

```ts file=figure/figure.ts
  MSO_ARROWHEAD,
  MSO_CONNECTOR,
  MSO_SHAPE,
  Pt,
  presentation,
} from "@allyhub/sdk/slides";

  { slides: "./figure.yaml", script: "./figure.{locale}.yaml" },
  (prs) => {
    prs.slide_masters.add("Blank").slide_layouts.add("Blank");
    prs.generators.add("figure", (g) => {
      const slide = g.slides.add_slide("Blank", "flow");
      const a = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, Pt(60), Pt(120), Pt(160), Pt(60));
      a.text_frame.text = "Encoder";
      const b = slide.shapes.add_shape(MSO_SHAPE.ROUNDED_RECTANGLE, Pt(360), Pt(120), Pt(160), Pt(60));
      b.text_frame.text = "Decoder";
      const c = slide.shapes.add_connector(MSO_CONNECTOR.STRAIGHT, 0, 0, Pt(1), 0);
      c.begin_connect(a, 3);
      c.end_connect(b, 1);
      c.line.end_arrow = MSO_ARROWHEAD.TRIANGLE;
    });
  },
);
```

```yaml
# figure/figure.yaml
slides:
  - id: figure
    generate: figure
```

```yaml
# figure/figure.en.yaml
slides: []
```

## The slides file

| Field               | What it is                                                                           |
| ------------------- | ------------------------------------------------------------------------------------ |
| `slides[].id`       | Unique in the deck: its row in the script                                            |
| `slides[].layout`   | One of the deck's layouts, by name                                                   |
| `slides[].generate` | One of the deck's generators: its slides stand here                                  |
| `slides[].hidden`   | `true`: left out when presenting and exporting; a block's: a list of its slides' ids |
| `slides[].shapes`   | Its shapes by name: what it changes of its layout's placeholders, and its own        |
| `slides[].background` | Its own background over its layout's: one of `fill` (a colour), `gradient` (as a shape's) or `picture` (a file, stretched over the slide) |

A shape there changes a placeholder of the slide's layout (or a generated shape) with `frame` (`{ x, y, w, h }` in points), `text` (on all of its text, every level, as PowerPoint sets a selected shape's: `size` in points, `bold`, `italic`, `underline`, `strike`, `color`, `font`, a family, `align`: `l`, `ctr`, `r`, `just`, `line_spacing`, a multiple of single spacing, `1.5`, `space_before` and `space_after` in points, `anchor`, where the text stands in its shape: `t`, `ctr`, `b`, `bullet`, a character, `"•"`, or `false` for none, `numbered`, its paragraphs counted in place of a bullet: `arabicPeriod`, `arabicParenR`, `alphaLcPeriod`, `alphaUcPeriod`, `romanLcPeriod`, `romanUcPeriod`; given both, `numbered` stands; a bullet or a number in text with no indent hangs as PowerPoint's does), `fill` (a colour, or `none`), `fill_transparency` (a share that shows through), `gradient` (`angle`, degrees clockwise from left to right, and `stops`, each `at`, a share of the way, `color` and `transparency`), `shadow` (`blur` and `distance` in points, `angle`, `color`, `transparency`), `line` (its outline: a colour, or `none`), `line_width` in points, `line_dash` (`solid`, `sysDash`, `sysDot`, `dash`, `dashDot`, `lgDash`, `lgDashDot`, `lgDashDotDot`), `line_begin` and `line_end` (`none`, `triangle`, `arrow`, `stealth`, `diamond`, `oval`), `line_begin_size` and `line_end_size` (`{ w, len }`, each `sm`, `med` or `lg`: the head's width and length, PowerPoint's Arrow size), `rotation` (degrees clockwise about its centre, 0 up to 360, python-pptx's `rotation`), `flip_h` and `flip_v` (`true`: mirrored left to right, top to bottom; a line runs from its frame's other corner; its text reads as it is), `crop` (a picture's: `left`, `top`, `right` and `bottom`, the share of it cut from each side, PowerPoint's `a:srcRect`; a negative share is space left beside it; the editor's Crop menu writes Fill and Fit, [pictures.md](https://allyhub.com/docs/reference/sdk/pictures.md#a-decks-pictures)), `z`; or is the slide's own with one of `textbox: true` (its words are the script's; it wraps, and grows from its frame's `h` to its text, so its frame still has all four of `x`, `y`, `w` and `h`), `picture`, `movie` (a video file of the project; a video item goes on a slide as its render, `allyhub render`), `geometry` (any of PowerPoint's 187 preset shapes by its `prst` name, ECMA-376's `ST_ShapeType`: `rect`, `roundRect`, `ellipse`, `triangle`, `star5`, `chevron`, `rightArrow`, `wedgeRectCallout`, `heart`, `cloud`, `donut`, `flowChartProcess`…, drawn from ECMA-376's preset shape definitions as PowerPoint draws them; a connector, `line`, `straightConnector1`, `bentConnector2` to `5` or `curvedConnector2` to `5`, has the connector's line, no fill and no text, and its `line_begin` and `line_end` face along its path, and `connect: { begin: { shape, site }, end: { shape, site } }` glues its ends to shapes of the slide by name, at sites of their geometries (a rectangle's 0 top, 1 left, 2 bottom, 3 right; PowerPoint's `a:stCxn` and `a:endCxn`): its frame is then where its ends sit, and they follow the shapes; `none` lets go of an end the code glued, as dragging the end off its shape does; with `adjustments`, its handles' values in the definition's order as python-pptx's `adjustments` has them, a share each: `roundRect`'s `[0.1]` is a corner of a tenth of its shorter side), `path` (a freeform: `{ w, h, d }`, its outline in a box of `w` × `h` units stretched to its frame, `d` in SVG's `M`, `L`, `C` and `Z`, absolute, so a logo or a cursor is a real shape), `table` (`columns`, widths in points, and `rows`, each a `height` with its `fill`, `text` and `line`, a rule at its foot; stretched to its frame, its words the script's, a list of rows, each a list of cells) or `component` (with `props`, and `dur`, how long it moves), and a `frame`. `group`, a name a slide's own shapes share, makes them one group in PowerPoint, standing together where the topmost of them stands. A table here has no style of its own, unlike python-pptx's: its look is what its rows and cells say. A picture or a movie put in a picture, media or object placeholder fills it. Colours are the theme's (`accent1`…); the theme's lighter or darker, in PowerPoint's words (`accent1 lighter 40%`, `dk1 darker 25%`, a share over 0 up to 100 %), which follows a change of theme as PowerPoint's picker's tints and shades do; or `#RRGGBB`. In code a colour (`ColorFormat`) has python-pptx's `brightness`, -1 to 1 (`0.4` is lighter 40 %), on a theme colour only. `z` orders a shape among the slide's shapes and placeholders, so a negative `z` puts one under a placeholder's words. Paths are from the deck's module's folder.

A slide's `animations` are PowerPoint's Animation Pane, in order, each on one of the slide's own shapes (`shape`, by name; in a block, `<slide>/<shape>`), or one `paragraph` of its text, from 0:

| Field | Default | What it is |
| --- | --- | --- |
| `effect` | | Entrances `appear`, `fade`, `wipe`, `fly-in`, `zoom`; exits `disappear`, `fade-out`, `wipe-out`, `fly-out`, `zoom-out`; `pulse`; `path` |
| `start` | `on-click` | `on-click`, `with-previous`, `after-previous`. What starts with no click before it plays as the slide opens |
| `direction` | `from-bottom` | A wipe's or a fly's side: `from-bottom`, `from-top`, `from-left`, `from-right` |
| `duration` | 0.5 (`appear`, `disappear` 0; `path` 2) | Seconds |
| `delay` | 0 | Seconds |
| `path` | | A `path` effect's, in points from where the shape stands, in SVG's `M`, `L` and `C`, absolute: `M0 0 L200 0` |

Each click is a step: its still, a page of a PDF, is drawn once what it started has ended, and `allyhub frames` has a tile for each. What a shape comes on by an entrance is not drawn before it. A component's `render(t)` is given the seconds since its shape came on, and a step that brings one on rests once it has settled. A PowerPoint file has them as PowerPoint's own. A generated slide adds them with `slide.animations.add(shape, effect, options)`.

A video on a slide plays from when its shape comes on, to its end, when presenting. In a PowerPoint file a component that moves is a video of what its code draws, from when its shape comes on, for as long as it moves (its `dur`, 4 seconds when absent), which plays as it comes on (as the slide opens, if it has no entrance); one that does not move is a picture.

A slide's `transition` is how it comes on from the slide before: `type` (`fade`, `push`, `wipe`, or `morph`), `direction` for a push or a wipe (`from-right` unless said), `duration` in seconds (0.7 for a fade, 1 for a push or a wipe, 2 for a morph). What is on the slide starts when it is over, and presenting plays it. A morph moves each shape the two slides share by name from the one's place and size to the other's, as PowerPoint's Morph; what only one has fades. So name a shape the same on both slides to carry it across. A PowerPoint file has them as its own, with a fade for a PowerPoint too old for Morph. A generated slide sets `slide.transition`.

A shape's `chart` is PowerPoint's own chart, with its numbers in a workbook a person opens with Edit Data. `type` is python-pptx's, in lower case: `column-clustered`, `column-stacked`, `column-stacked-100`, the same three of `bar`, `line`, `line-markers`, `area`, `area-stacked`, `area-stacked-100`, `pie`, `doughnut`, and XY's `scatter`, `scatter-lines` and `scatter-smooth`, each series with an `x` beside its `values`, or with `data`, `categories` naming the column across. There is no 3D, bubble, radar or second axis. Its numbers are written in it, or read from a project file, so a slide shows what the sheet says:

```yaml
revenue:
  frame: { x: 80, y: 120, w: 640, h: 340 }
  chart:
    type: column-clustered
    data: ../sales/sales.yaml#revenue # from the module's folder: a sheet's table (<sheet>#<table>), a CSV, or a data file of rows
    categories: Quarter # the column of names
    series: [Revenue, { name: Cost, color: accent3 }] # the columns of numbers
    legend: bottom
```

Without `data`, `categories` is a list of names and each series has its `values` (one per category, `null` for none). A value read from a file is a plain number. A column that is not there, a cell that is not a number, or values that do not fit the categories are AK-M011, with what the file has. The chart's title is the script's: the shape's words.

| Field | Default | What it is |
| --- | --- | --- |
| `legend` | none | `bottom`, `top`, `left`, `right` |
| `labels` | none | `true`: each value. Or `value`, `percentage` (a pie's and a doughnut's), `category`, `series`, `format`, `position`, `size`, `color` |
| `labels.position` | a clustered bar's `outEnd`, a stacked bar's and a pie's `ctr`, a line's `t` | `outEnd` (clustered bars and pies), `inEnd`, `ctr`, `inBase` (bars), `t`, `b`, `l`, `r` (lines). An area and a doughnut have none: a position a chart's kind cannot have is AK-M011, since PowerPoint would repair the file |
| `gap_width`, `overlap` | 150; 0 (stacked 100) | Bars: the gap as a share of a bar's width, how far one covers the next, in % |
| `vary_by_categories` | a pie's and a doughnut's | A colour per category |
| `category_colors` | the accents in turn | Where it varies by categories, each category's colour in order (a slice's): a theme colour or `#RRGGBB`. In code, a series' `points[i].format.fill`, as python-pptx's |
| `hole_size` | 50 | A doughnut's, in % |
| `value_axis`, `category_axis` | automatic | `min`, `max`, `major`, `gridlines` (the value axis's are on), `visible`, `format` (Excel's), `reverse`, `gridline_color`, `line_color` |
| `size`, `title_size`, `color` | 12, 14.4, `dk1` | Its text's points, its title's, and their colour |
| a series' `color`, `format`, `smooth`, `line_width`, `marker_size` | the accents in turn, `General`, off, 2.25, 5 | |

In code, `shapes.add_chart(XL_CHART_TYPE.X, left, top, width, height, chart_data)` makes one from a `CategoryChartData`, or an `XyChartData` (`add_series(name)`, `add_data_point(x, y)`), as python-pptx's does, with its `.chart`. A scale left automatic is PowerPoint's in the file and drawn here by the same rules, so a number a person changes moves it; set `min`, `max` and `major` to fix it. Where the plot sits is written in the file, so every app puts it where the stage does. `allyhub inspect --kind chart-data` lists each chart's numbers and the file they came from.

What the slides file names that the deck does not have (a layout, a generator, a component or its prop, a shape to change or animate, a file) is AK-M011, at its line; an exception in a generator, at the line of the deck's module that threw it. A slide that is not the format is left out, so one check finds every problem.

## The script

A deck's script has a row per slide under `slides`: its `text` by shape name (a placeholder's or a text box's; a list is paragraphs, a list in it a level deeper; `**bold**`, `*italic*`, `` `code` ``, in the theme's `code` font, `<span color="accent1" font="Inter Tight">words</span>`, in a colour as the slides file writes one (`accent1`, `accent1 lighter 40%`, `#RRGGBB`), a font of their own, or both, are runs, as in a doc; a span also takes `size="24"`, in points, `bold="false"` and `italic="false"`, plain words in a bold or italic level, `underline="true"`, `link="https://…"`, `strike="true"`, `highlight="#FFFF00"` and `baseline="0.3"`, raised or, below 0, lowered, a share of the size. A slide number placeholder writes its own text, a number PowerPoint keeps up to date) its `alt`, each picture's or shape's alternative text by name (what a screen reader says, PowerPoint's Alt Text), and its `notes`. A key is `<prefix>.<slide>.<shape>` (the prefix is the deck's id with `/` as `.`), `<prefix>.<slide>.alt.<shape>`, `<prefix>.<slide>.notes`. A placeholder with no words in the script is empty, and an empty placeholder is not drawn. A layout's date, footer and slide number placeholders are on a slide only where it names them in the slides file (`slide-number: {}`), as PowerPoint's Header & Footer and python-pptx's `add_slide` have it. Words are in the script's language, and in Japanese where they have kana, Korean where they have hangul, on the stage and in an exported file: Han characters take that language's forms.

## What a person changes in the editor

The slides' order, a slide's layout, hidden, added, duplicated or removed; text typed in place and the notes; a shape moved and sized, brought forward or sent back, removed; a text box, picture, video or basic shape placed; a theme colour for a fill or a text, a text's size, bold and alignment; a shape reset to its layout. Every one of these is an edit of the slides file or the script; everything else (masters, layouts, components, generators, style beyond these) is yours, in the deck's module. When you and the person change these files at once, both changes stand: a frame, a shape and an animation merge field by field, the slides' order and a shape's paragraphs line by line, and where you both changed one value the person's stands; a slide or shape one of you removed while the other changed it stays, changed. The person keeps or undoes each of your changes. A slide the person adds is `slide-` and four letters (`slide-k3f9`), so give yours ids by what they are.

## Importing a PowerPoint file

`allyhub slides import <file.pptx> --to reviews/q3.ts` makes a deck of a PowerPoint file: its masters and layouts as the deck's module, `reviews/q3.ts` (python-pptx's calls, only what differs from Office's text styles; by default the file's name, `.ts`), its slides on their layouts as its slides file, `reviews/q3.yaml` (what each moves, its own shapes, pictures, videos, tables, charts and lines, their rotation, flips and groups, its background, animations and transition), each slide's words, alternative text and notes as the script, `reviews/q3.<lang>.yaml` (bold and italic as `**…**` and `*…*`, a run's own bold or italic off as `bold="false"` or `italic="false"`, a link, a highlight, a baseline, a colour, a font, a size, an underline or a strike of their own as spans, what all of a shape's text has as its `text` in the slides file, a deeper level as a list in the list), its pictures and videos beside them, by their files' names (another where a file there has it). A slide's and a shape's name is kept where it is a name (letters, digits, `_`, `-`), so a deck AllyHub wrote reads back with its own. A table's style is resolved into its rows' fills, text and rules; a theme colour lightened or darkened as PowerPoint's picker does it is that theme colour (`accent1 lighter 40%`), one changed otherwise the colour it makes.

Everything the file holds that the deck does not carry over as it is is reported, grouped (what, why, how many, where), all of it with `--json`: what nothing read, an extension of Office's, a part, what the deck cannot hold, what is held another way, what is missing from the file. Nothing is dropped without a line. `--lang` names the script's language.

## Measuring a deck

The check measures every slide as the stage draws it, and `allyhub inspect` lists what it found as facts: numbers for you to judge, never problems, every length in points as the slides file writes them. Text the slide's edge cuts at every build that shows it is AK-L002, an error that stops a render. A deck has:

- `text-overflow`: a shape's text past its box, by its lines' glyphs.
- `text-off-slide`: a shape's text the slide's edge cuts, how far and the share outside.
- `shape-off-slide`, `shape-overlap`, `shape-hidden`: a shape past the slide's edge, two over each other (what shows of each: a filled shape or a picture whole, a text's glyphs), one covered whole.
- `near-alignment`: edges and centres of two shapes, or of a shape and the slide's centre, nearly in line and not: where each line is, whether it is a frame or a text's glyphs, and the frame's `x` or `y` that aligns them (`allyhub inspect layout --within <pt>`).
- `placement-drift`: a shape of one name at different places on slides of one layout (`--drift <pt>`).
- `type-in-use`, `read-size`, `words-on-slide`: the sizes and weights in use, each text's size on a phone (with `--room`, on a room's screen too), the words on each slide.
- `picture-resolution`: a picture drawn larger than its pixels, or stretched.

`allyhub frames <deck> --overlay` draws each shape's box and name over its slide, and the lines nearly in line; `allyhub inspect contrast` measures text against what is behind it.

## What a deck renders to

`allyhub render` makes a deck's files in `.allyhub/out/`, named by its id (`reviews/q3.<combo key>.<ext>`), each slide drawn at its still, hidden ones left out; `allyhub help render` lists the options.

| Type                | What it is                                                |
| ------------------- | --------------------------------------------------------- |
| `pdf` (the default) | A page per slide, the slide's size, the text kept as text and a link a link; titled as the deck, an outline entry per slide by its title; the same bytes every time (no date in it unless `SOURCE_DATE_EPOCH` is set) |
| `png`               | A picture per slide, numbered from 1                      |
| `pptx`              | PowerPoint's own file: the deck's theme, masters with their text styles, layouts with their placeholders, each slide's placeholders, text, shapes, pictures, videos and notes, editable as any deck. A component (or a coded video) is a picture of it as drawn. `--param pptx=picture` makes each slide a picture instead |

Every combo of the deck (its languages) renders its own files. `allyhub frames` draws every slide's still on one sheet.
