File Coverage

blib/lib/PDF/Make/Builder.pm

Criterion	Covered	Total	%
statement	883	918	96.1
branch	221	292	75.6
condition	184	321	57.3
subroutine	130	132	98.4
pod	58	79	73.4
total	1476	1742	84.7

package PDF::Make::Builder;
use strict;
use warnings;
use File::Basename qw(dirname);
use File::Path qw(make_path);
use Object::Proto;
use PDF::Make::Document;
use PDF::Make::Canvas;
use PDF::Make::Import;
use PDF::Make::Page qw(:fonts);
use PDF::Make::Builder::Font;
use PDF::Make::Builder::Page;
use PDF::Make::Builder::Page::Header;
use PDF::Make::Builder::Page::Footer;
use PDF::Make::Builder::Text;
use PDF::Make::Builder::Text::H1;
use PDF::Make::Builder::Text::H2;
use PDF::Make::Builder::Text::H3;
use PDF::Make::Builder::Text::H4;
use PDF::Make::Builder::Text::H5;
use PDF::Make::Builder::Text::H6;
use PDF::Make::Builder::Shape::Line;
use PDF::Make::Builder::Shape::Box;
use PDF::Make::Builder::Shape::Circle;
use PDF::Make::Builder::Shape::Ellipse;
use PDF::Make::Builder::Shape::Pie;
use PDF::Make::Builder::TOC;
use PDF::Make::Builder::Image;
use PDF::Make::Builder::Layout;
use PDF::Make::Builder::Form::Field;
use PDF::Make::Builder::Form::Field::Text;
use PDF::Make::Builder::Form::Field::Checkbox;
use PDF::Make::Builder::Form::Field::Radio;
use PDF::Make::Builder::Form::Field::Combo;
use PDF::Make::Builder::Form::Field::Listbox;
use PDF::Make::Builder::Form::Field::Button;
use PDF::Make::Attachment;
use PDF::Make::Color;
use PDF::Make::Extract;
use PDF::Make::Extract::Result;
use PDF::Make::Font;
use PDF::Make::Layer;
use PDF::Make::Parser;
use PDF::Make::Reader;
use PDF::Make::Redaction;
use PDF::Make::Signature;
use PDF::Make::Structure;
use PDF::Make::Watermark;

our $VERSION = '0.03';

BEGIN {
    Object::Proto::define('PDF::Make::Builder',
        'file_name:Str:required',
        'doc:Any',
        'pages:ArrayRef:default([])',
        'page:Any',
        'page_args:HashRef:default({})',
        'page_offset:Int:default(0)',
        'onsave_cbs:ArrayRef:default([])',
        'configure:HashRef:default({})',
        'font:Any',
        'toc:Any',
        '_header_args:HashRef',
        '_footer_args:HashRef',
        '_outlines:HashRef:default({})',
        '_layers:HashRef:default({})',
        '_encrypt_args:HashRef',
        '_sign_args:HashRef',
        '_watermarks:ArrayRef:default([])',
        '_tagging:Any',
        '_struct_tree:Any',
        '_struct_stack:ArrayRef:default([])',
        '_flatten_pending:Bool:default(0)',
        '_apply_redactions_pending:Bool:default(0)',
        '_sanitize_pending:Bool:default(0)',
    );
    Object::Proto::import_accessors('PDF::Make::Builder');
}

sub BUILD {
    my ($self) = @_;
    doc $self, PDF::Make::Document->new;

    # Default font
    my $cfg = configure $self;
    my $font_args = $cfg->{text}{font} // {};
    my %font_init = (
        colour => $font_args->{colour} // '#000',
        size   => $font_args->{size}   // 9,
        family => $font_args->{family} // 'Helvetica',
    );
    $font_init{line_height} = $font_args->{line_height} if defined $font_args->{line_height};
    font $self, PDF::Make::Builder::Font->new(%font_init);

    # Store header/footer config for new pages
    if ($cfg->{page_header}) {
        _header_args $self, $cfg->{page_header};
    }
    if ($cfg->{page_footer}) {
        _footer_args $self, $cfg->{page_footer};
    }
}

# ── Page management ────────────────────────────────────────

sub add_page {
    my ($self, %args) = @_;

    my $page_size = $args{page_size} // 'A4';
    my ($pw, $ph) = PDF::Make::Builder::Page::page_dimensions($page_size);
    my $padding = $args{padding} // 20;
    my $xs_doc = doc $self;
    my $xs_page = $xs_doc->add_page($pw, $ph);
    my $canvas = PDF::Make::Canvas->new;

    my $pages = pages $self;
    my $num = scalar(@$pages) + 1;

    # Build header/footer from stored config
    my $hdr_args = _header_args $self;
    my $ftr_args = _footer_args $self;
    my $header = $hdr_args ? PDF::Make::Builder::Page::Header->new(%$hdr_args) : undef;
    my $footer = $ftr_args ? PDF::Make::Builder::Page::Footer->new(%$ftr_args) : undef;

    my $bp = PDF::Make::Builder::Page->new(
        page_size  => $page_size,
        background => $args{background} // '#fff',
        columns    => $args{columns}    // 1,
        padding    => $padding,
        num        => $num,
        w          => $pw,
        h          => $ph,
        canvas     => $canvas,
        xs_page    => $xs_page,
        header     => $header,
        footer     => $footer,
    );

    # Draw background if not white
    my $bg = $bp->background;
    if ($bg && $bg ne '#fff' && $bg ne '#ffffff') {
        my ($r, $g, $b) = (font $self)->hex_to_rgb($bg);
        $canvas->q->rg($r, $g, $b)->re(0, 0, $pw, $ph)->f->Q;
    }

    push @$pages, $bp;
    pages $self, $pages;
    page $self, $bp;

    return $self;
}

sub open_page {
    my ($self, $num) = @_;
    my $pages = pages $self;
    die "PDF::Make::Builder: page $num does not exist" unless $num >= 1 && $num <= scalar @$pages;
    page $self, $pages->[$num - 1];
    return $self;
}

sub set_columns {
    my ($self, $n) = @_;
    my $p = page $self;
    die "PDF::Make::Builder: no current page" unless $p;
    $p->columns($n);
    return $self;
}

sub page_width {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->w : 0;
}

sub page_height {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->h : 0;
}

sub current_x {
    my ($self) = @_;
    my $p = page $self;
    return $p ? ($p->x || $p->content_x) : 0;
}

sub current_y {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->cursor_y : 0;
}

sub content_left {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->content_x : 0;
}

sub content_right {
    my ($self) = @_;
    my $p = page $self;
    return $p ? ($p->content_x + $p->width) : 0;
}

sub content_bottom {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->bottom_y : 0;
}

sub content_top {
    my ($self) = @_;
    my $p = page $self;
    return $p ? $p->top_y : 0;
}

sub cursor_move_to {
    my ($self, $x, $y) = @_;
    my $p = page $self;
    die "PDF::Make::Builder: no current page" unless $p;
    $p->x($x) if defined $x;
    $p->y($y) if defined $y;
    return $self;
}

sub cursor_advance_y {
    my ($self, $dy) = @_;
    my $p = page $self;
    die "PDF::Make::Builder: no current page" unless $p;
    $dy //= 0;
    $p->y($p->cursor_y + $dy);
    return $self;
}

# ── Layout ────────────────────────────────────────────────

sub layout {
    my ($self) = @_;
    return PDF::Make::Builder::Layout->new(builder => $self);
}

# ── Header/Footer ─────────────────────────────────────────

sub add_page_header {
    my ($self, %args) = @_;
    _header_args $self, \%args;
    my $p = page $self;
    if ($p) {
        $p->header(PDF::Make::Builder::Page::Header->new(%args));
    }
    return $self;
}

sub add_page_footer {
    my ($self, %args) = @_;
    _footer_args $self, \%args;
    my $p = page $self;
    if ($p) {
        $p->footer(PDF::Make::Builder::Page::Footer->new(%args));
    }
    return $self;
}

sub remove_page_header {
    my ($self) = @_;
    _header_args $self, undef;
    my $p = page $self;
    $p->header(undef) if $p;
    return $self;
}

sub remove_page_footer {
    my ($self) = @_;
    _footer_args $self, undef;
    my $p = page $self;
    $p->footer(undef) if $p;
    return $self;
}

sub remove_page_header_and_footer {
    my ($self) = @_;
    $self->remove_page_header;
    $self->remove_page_footer;
    return $self;
}

# ── Font ───────────────────────────────────────────────────

sub load_font {
    my ($self, %args) = @_;
    font $self, PDF::Make::Builder::Font->new(%args);
    return $self;
}

# ── Text content ───────────────────────────────────────────

sub _apply_configure {
    my ($self, $type, $args) = @_;
    my $cfg = configure $self;
    my $defaults = $cfg->{$type} // {};
    if ($defaults->{font}) {
        $args->{font} = { %{$defaults->{font}}, %{$args->{font} // {}} };
    }
    return $args;
}

sub _tag_begin {
    my ($self, $tag_type) = @_;
    return unless _tagging $self;
    my $tree = _struct_tree $self;
    return unless $tree;
    my $stack = _struct_stack $self;
    my $parent = @$stack ? $stack->[-1] : $tree->root;
    my $elem = $parent->add_child($tag_type);
    push @$stack, $elem;
    _struct_stack $self, $stack;
}

sub _tag_end {
    my ($self) = @_;
    return unless _tagging $self;
    my $stack = _struct_stack $self;
    pop @$stack if @$stack;
    _struct_stack $self, $stack;
}

sub add_text {
    my ($self, %args) = @_;
    $self->_apply_configure('text', \%args);
    $self->_tag_begin('P');
    my $t = PDF::Make::Builder::Text->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h1 {
    my ($self, %args) = @_;
    $self->_apply_configure('h1', \%args);
    $self->_tag_begin('H1');
    my $t = PDF::Make::Builder::Text::H1->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h2 {
    my ($self, %args) = @_;
    $self->_apply_configure('h2', \%args);
    $self->_tag_begin('H2');
    my $t = PDF::Make::Builder::Text::H2->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h3 {
    my ($self, %args) = @_;
    $self->_apply_configure('h3', \%args);
    $self->_tag_begin('H3');
    my $t = PDF::Make::Builder::Text::H3->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h4 {
    my ($self, %args) = @_;
    $self->_apply_configure('h4', \%args);
    $self->_tag_begin('H4');
    my $t = PDF::Make::Builder::Text::H4->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h5 {
    my ($self, %args) = @_;
    $self->_apply_configure('h5', \%args);
    $self->_tag_begin('H5');
    my $t = PDF::Make::Builder::Text::H5->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_h6 {
    my ($self, %args) = @_;
    $self->_apply_configure('h6', \%args);
    $self->_tag_begin('H6');
    my $t = PDF::Make::Builder::Text::H6->new(%args);
    $t->add($self);
    $self->_tag_end;
    return $self;
}

sub add_lines {
    my ($self, @lines) = @_;
    for my $line (@lines) {
        if (ref $line eq 'HASH') {
            $self->add_text(%$line);
        } else {
            $self->add_text(text => $line);
        }
    }
    return $self;
}

# ── Shapes ─────────────────────────────────────────────────

sub add_line {
    my ($self, %args) = @_;
    my $s = PDF::Make::Builder::Shape::Line->new(%args);
    $s->add($self);
    return $self;
}

sub add_box {
    my ($self, %args) = @_;
    my $s = PDF::Make::Builder::Shape::Box->new(%args);
    $s->add($self);
    return $self;
}

sub add_circle {
    my ($self, %args) = @_;
    my $s = PDF::Make::Builder::Shape::Circle->new(%args);
    $s->add($self);
    return $self;
}

sub add_ellipse {
    my ($self, %args) = @_;
    my $s = PDF::Make::Builder::Shape::Ellipse->new(%args);
    $s->add($self);
    return $self;
}

sub add_pie {
    my ($self, %args) = @_;
    my $s = PDF::Make::Builder::Shape::Pie->new(%args);
    $s->add($self);
    return $self;
}

# ── Images ─────────────────────────────────────────────────

sub add_image {
    my ($self, %args) = @_;
    $self->_tag_begin('Figure');
    my $img = PDF::Make::Builder::Image->new(%args);
    $img->add($self);
    $self->_tag_end;
    return $self;
}

# ── Metadata ───────────────────────────────────────────────

sub title {
    my ($self, $val) = @_;
    (doc $self)->title($val);
    return $self;
}

sub author {
    my ($self, $val) = @_;
    (doc $self)->author($val);
    return $self;
}

sub subject {
    my ($self, $val) = @_;
    (doc $self)->subject($val);
    return $self;
}

sub keywords {
    my ($self, $val) = @_;
    (doc $self)->keywords($val);
    return $self;
}

sub creator {
    my ($self, $val) = @_;
    (doc $self)->creator($val);
    return $self;
}

sub producer {
    my ($self, $val) = @_;
    (doc $self)->producer($val);
    return $self;
}

# ── Outlines/Bookmarks ────────────────────────────────────

sub add_outline {
    my ($self, $title, %args) = @_;
    my $page_index = $args{page} // 0;
    my $dest_type  = $args{dest} // 'Fit';
    my $parent_key = $args{parent};
    my $left       = $args{left} // 0;
    my $top        = $args{top}  // 0;
    my $zoom       = $args{zoom} // 0;

    my $outlines = _outlines $self;
    my $item;

    if ($parent_key && $outlines->{$parent_key}) {
        $item = $outlines->{$parent_key}->add_child(
            $title, $page_index, $dest_type, $left, $top, $zoom
        );
    } else {
        $item = (doc $self)->add_outline(
            $title, $page_index, $dest_type, $left, $top, $zoom
        );
    }

    $outlines->{$title} = $item;
    _outlines $self, $outlines;
    return $self;
}

# ── Links/Actions ─────────────────────────────────────────

sub add_link {
    my ($self, %args) = @_;
    my $xs_doc = doc $self;

    my $target_builder_page;
    if (defined $args{on_page}) {
        my $idx = $args{on_page};
        my $all = pages $self;
        die "PDF::Make::Builder: on_page $idx does not exist" unless $all && $idx >= 0 && $idx < @$all;
        $target_builder_page = $all->[$idx];
    } else {
        $target_builder_page = page $self;
        die "PDF::Make::Builder: add_link requires a current page" unless $target_builder_page;
    }

    my $rect;
    if ($args{rect}) {
        $rect = $args{rect};
    } elsif (defined $args{x} || defined $args{y} || defined $args{w} || defined $args{h}) {
        die "PDF::Make::Builder: add_link builder coords require x,y,w,h"
            unless defined $args{x} && defined $args{y} && defined $args{w} && defined $args{h};

        my ($x, $y, $w, $h) = @args{qw/x y w h/};
        my $x0 = $x;
        my $x1 = $x + $w;
        my $y0 = $y;
        my $y1 = $y + $h;
        $rect = [$x0, $y0, $x1, $y1];
    } else {
        die "PDF::Make::Builder: add_link requires rect => [x0,y0,x1,y1] or builder coords x,y,w,h";
    }

    my $hl = $args{highlight} // 'Invert';
    my $annot_num;

    if ($args{url}) {
        $annot_num = $xs_doc->add_link_uri(@$rect, $args{url});
    } elsif (defined $args{page}) {
        $annot_num = $xs_doc->add_link_goto(@$rect, $args{page});
    } elsif ($args{action}) {
        # Named action: NextPage, PrevPage, FirstPage, LastPage, Print
        $annot_num = $xs_doc->add_link_named_action(@$rect, $args{action}, $hl);
    } elsif ($args{file}) {
        # External PDF link (GoToR)
        my $action = $xs_doc->action_gotor($args{file}, $args{file_page} // 0, $args{new_window} // 0);
        $annot_num = $xs_doc->add_link_with_action(@$rect, $action, $hl);
    } else {
        die "PDF::Make::Builder: add_link requires url, page, action, or file";
    }

    if ($annot_num) {
        my $page_obj;
        if (defined $args{on_page}) {
            my $target_page = $args{on_page};
            $page_obj = $xs_doc->get_page($target_page);
            die "PDF::Make::Builder: on_page $target_page does not exist" unless $page_obj;
        } else {
            $page_obj = $target_builder_page->xs_page;
        }
        $page_obj->add_annot($annot_num);
    }
    return $self;
}

# ── Annotations ──────────────────────────────────────────

sub add_note {
    my ($self, %args) = @_;

    # Visual note mode: draw a coloured callout box with lines of text
    if (exists $args{lines} || (exists $args{text} && ref $args{text} eq 'ARRAY')) {
        my $lines      = $args{lines} // $args{text};
        my $x          = $args{x}          // 72;
        my $w          = $args{w}          // 300;
        my $h          = $args{h}          // 70;
        my $bg         = $args{bg_colour}  // $args{fill_colour} // '#fffbeb';
        my $padding    = $args{padding}    // 12;
        my $line_gap   = $args{line_gap}   // 14;
        my $colour     = $args{colour}     // '#92400e';
        my $size       = $args{size}       // 10;

        my $cur = page $self;
        die "PDF::Make::Builder: add_note requires a current page" unless $cur;

        my $y;
        if (defined $args{y}) {
            $y = $args{y};
        } else {
            $y = $cur->cursor_y - $h;
            $cur->advance_y($h + 6);
        }

        $self->add_box(fill_colour => $bg, x => $x, y => $y, w => $w, h => $h);

        my $ty = $y + $h - $padding - $size;
        for my $line (@$lines) {
            my ($text, $fsize, $fcol, $italic) =
                ref $line eq 'HASH'
                    ? (@{$line}{qw(text size colour italic)})
                    : ($line, undef, undef, 0);
            $fsize //= $size;
            $fcol  //= $colour;
            $self->add_text(
                text => $text,
                x    => $x + $padding,
                y    => $ty,
                w    => $w - $padding * 2,
                font => { size => $fsize, colour => $fcol, ($italic ? (italic => 1) : ()) },
            );
            $ty -= $line_gap;
        }
        return $self;
    }

    # Annotation note mode (PDF sticky note)
    my $xs_doc = doc $self;
    my $rect = $args{rect} // die "PDF::Make::Builder: add_note requires rect or lines";
    my $text = $args{text} // '';
    my $icon = $args{icon} // 'Note';
    my $open = $args{open} // 0;

    # Resolve target page (defaults to current)
    my $target = $args{page};
    my $xs_page;
    if (defined $target) {
        my $ps = pages $self;
        die "PDF::Make::Builder: add_note: page index out of range"
            unless $target >= 0 && $target < scalar @$ps;
        $xs_page = $ps->[$target]->xs_page;
    } else {
        my $cur = page $self or die "PDF::Make::Builder: add_note requires a current page";
        $xs_page = $cur->xs_page;
    }

    my $annot_num = $xs_doc->add_text_annot(@$rect, $text, $icon, $open);
    $xs_page->add_annot($annot_num) if $annot_num;
    return $self;
}

sub add_stamp {
    my ($self, %args) = @_;

    # Visual stamp mode: draw a coloured box with centred bold label
    if (exists $args{text}) {
        my $text       = $args{text};
        my $x          = $args{x} // 72;
        my $w          = $args{w} // 200;
        my $h          = $args{h} // 50;
        my $bg         = $args{bg_colour}   // $args{fill_colour} // '#e5e7eb';
        my $colour     = $args{colour}      // '#111827';
        my $size       = $args{size}        // 20;
        my $border     = $args{border}      // 0;
        my $border_col = $args{border_colour} // $colour;

        my $cur = page $self;
        die "PDF::Make::Builder: add_stamp requires a current page" unless $cur;

        my $y;
        if (defined $args{y}) {
            $y = $args{y};
        } else {
            $y = $cur->cursor_y - $h;
            $cur->advance_y($h + 6);
        }

        $self->add_box(
            fill_colour   => $bg,
            x             => $x,
            y             => $y,
            w             => $w,
            h             => $h,
            ($border ? (border_colour => $border_col, border_width => $border) : ()),
        );
        $self->add_text(
            text  => $text,
            x     => $x,
            y     => $y + ($h / 2) + ($size * 0.66),
            w     => $w,
            align => 'center',
            font  => { size => $size, colour => $colour, bold => 1 },
        );
        return $self;
    }

    # Annotation stamp mode
    my $xs_doc = doc $self;
    my $rect = $args{rect} // die "PDF::Make::Builder: add_stamp requires rect or text";
    my $type = $args{type} // 'Draft';
    $xs_doc->add_stamp(@$rect, $type);
    return $self;
}

# ── Bates Numbering ──────────────────────────────────────

sub add_bates {
    my ($self, %args) = @_;
    my $stamp = PDF::Make::Stamp->bates(%args);
    my $xs_doc = doc $self;
    no warnings 'uninitialized';
    $xs_doc->apply_stamp($stamp);
    return $self;
}

# ── Custom Metadata ──────────────────────────────────────

sub set_meta {
    my ($self, $key, $value) = @_;
    (doc $self)->set_meta($key, $value);
    return $self;
}

sub get_meta {
    my ($self, $key) = @_;
    return (doc $self)->get_meta($key);
}

# ── Page Info ────────────────────────────────────────────

sub page_count {
    my ($self) = @_;
    return scalar @{pages $self};
}

# ── Output ───────────────────────────────────────────────

sub to_bytes {
    my ($self) = @_;

    # Finalize all pages (same as save but return bytes)
    my $all_pages = pages $self;
    my $offset = page_offset $self;
    my $rewrite = _apply_redactions_pending $self;
    for my $bp (@$all_pages) {
        next if $bp->imported;
        my $hdr = $bp->header;
        my $ftr = $bp->footer;
        my $pnum = $bp->num + $offset;
        $hdr->render($self, $bp, $pnum) if $hdr;
        $ftr->render($self, $bp, $pnum) if $ftr;
        my $bytes = ($rewrite && @{$bp->redactions})
            ? $self->_rewrite_redacted_canvas_bytes($bp)
            : $bp->canvas->to_bytes;
        $bp->xs_page->set_content($bytes);
    }

    if (_sanitize_pending $self) {
        PDF::Make::Redaction->sanitize(doc $self);
    }

    # Finalize form
    {
        my $xs_doc = doc $self;
        my $form = eval { PDF::Make::FormPtr::get($xs_doc) };
        if ($form) {
            PDF::Make::FormPtr::finalize($form);
        }
    }

    return (doc $self)->to_bytes;
}

# ── Attachments ───────────────────────────────────────────

sub attach {
    my ($self, %args) = @_;
    my $xs_doc = doc $self;
    PDF::Make::Attachment->attach($xs_doc, %args);
    return $self;
}

# ── Watermarks ────────────────────────────────────────────

sub add_watermark {
    my ($self, %args) = @_;
    my $text = delete $args{text} // die "PDF::Make::Builder: add_watermark requires text";
    my $wm = PDF::Make::Watermark->text($text, %args);
    my $wms = _watermarks $self;
    push @$wms, $wm;
    _watermarks $self, $wms;
    return $self;
}

# ── Encryption ────────────────────────────────────────────

sub encrypt {
    my ($self, %args) = @_;
    _encrypt_args $self, \%args;
    return $self;
}

# ── Layers/OCG ────────────────────────────────────────────

sub add_layer {
    my ($self, $name, %args) = @_;
    my $xs_doc = doc $self;
    my $layer = PDF::Make::Layer->create($xs_doc, $name);
    $layer->visible($args{visible}) if defined $args{visible};
    my $num = $layer->write_to_doc($xs_doc);
    my $cur = page $self;
    if ($cur) {
        $cur->xs_page->add_ocg($layer->res_name, $num);
    }
    my $layers = _layers $self;
    $layers->{$name} = $layer;
    _layers $self, $layers;
    return $self;
}

sub begin_layer {
    my ($self, $name) = @_;
    my $layers = _layers $self;
    my $layer = $layers->{$name} // die "PDF::Make::Builder: unknown layer '$name'";
    my $cur = page $self;
    die "PDF::Make::Builder: no current page" unless $cur;
    $cur->canvas->begin_layer($layer->res_name);
    return $self;
}

sub end_layer {
    my ($self) = @_;
    my $cur = page $self;
    die "PDF::Make::Builder: no current page" unless $cur;
    $cur->canvas->end_layer;
    return $self;
}

# ── Redaction ─────────────────────────────────────────────

sub mark_redaction {
    my ($self, %args) = @_;
    my $page_index = delete $args{page} // 0;
    my $ps = pages $self;
    die "PDF::Make::Builder: page index out of range"
        unless $page_index >= 0 && $page_index < scalar @$ps;

    my $bp = $ps->[$page_index];

    # Register the /Redact annotation for downstream tools.
    PDF::Make::Redaction->mark($bp->xs_page, %args);

    my $rect = $args{rect} or return $self;
    my ($x0, $y0, $x1, $y1) = @$rect;
    my ($w, $h) = ($x1 - $x0, $y1 - $y0);
    return $self if $w <= 0 || $h <= 0;

    my $colour = $args{overlay_colour} // $args{overlay_color} // '#000';
    my $text   = $args{overlay_text};
    my $size   = $args{overlay_font_size} // 10;

    # Remember the redaction so save-time can rewrite the content stream
    # to actually remove text that falls inside the rect, then repaint
    # the overlay on top of the filtered stream.
    my $list = $bp->redactions;
    push @$list, {
        rect         => [$x0, $y0, $x1, $y1],
        overlay_text => $text,
        overlay_size => $size,
        overlay_fill => $colour,
    };
    $bp->redactions($list);

    # Eagerly paint the opaque cover so that even a user who never calls
    # apply_redactions sees the sensitive area visually hidden.
    my $font   = $self->font;
    my ($r, $g, $b) = $font->hex_to_rgb($colour);
    my $canvas = $bp->canvas;

    $canvas->q->rg($r, $g, $b)->re($x0, $y0, $w, $h)->f->Q;

    if (defined $text && length $text) {
        my $res = $font->ensure_loaded($bp->xs_page, 'normal');
        my ($tr, $tg, $tb) = $font->hex_to_rgb('#fff');
        my $tw = $font->measure_text($text) * ($size / ($font->size || 9));
        my $tx = $x0 + ($w - $tw) / 2;
        $tx = $x0 + 4 if $tw > $w - 4;
        my $ty = $y0 + ($h - $size) / 2 + 1;
        $canvas->q
               ->BT
               ->rg($tr, $tg, $tb)
               ->Tf($res, $size)
               ->Tm(1, 0, 0, 1, $tx, $ty)
               ->Tj($text)
               ->ET
               ->Q;
    }

    return $self;
}

sub apply_redactions {
    my ($self) = @_;
    _apply_redactions_pending $self, 1;
    return $self;
}

sub sanitize {
    my ($self) = @_;
    _sanitize_pending $self, 1;
    return $self;
}

# Internal: filter the canvas bytes for one page through the redaction
# rewriter and re-paint overlay text.  Called from save() / to_bytes()
# when $builder->_apply_redactions_pending is set.
sub _rewrite_redacted_canvas_bytes {
    my ($self, $bp) = @_;
    my $reds = $bp->redactions;
    return $bp->canvas->to_bytes unless $reds && @$reds;

    my $raw_bytes = $bp->canvas->to_bytes;
    my @rects = map { $_->{rect} } @$reds;
    my $filtered = PDF::Make::Redaction->rewrite_stream($raw_bytes, \@rects);

    # Re-paint overlay text for each redaction on a fresh small canvas
    # so those BT..ET blocks come AFTER the filtered stream and are not
    # themselves dropped by the filter.
    my $overlay_canvas = PDF::Make::Canvas->new;
    my $font = $self->font;
    for my $r (@$reds) {
        my ($x0, $y0, $x1, $y1) = @{$r->{rect}};
        my ($w, $h) = ($x1 - $x0, $y1 - $y0);
        next if $w <= 0 || $h <= 0;

        # Black rect (re-paint since the filter kept the original, but
        # redundant paints are harmless and guard against any edge case
        # where the original rect op was adjacent to a dropped block).
        my ($br, $bg, $bb) = $font->hex_to_rgb($r->{overlay_fill} // '#000');
        $overlay_canvas->q->rg($br, $bg, $bb)->re($x0, $y0, $w, $h)->f->Q;

        my $text = $r->{overlay_text};
        next unless defined $text && length $text;

        my $size = $r->{overlay_size} || 10;
        my $res  = $font->ensure_loaded($bp->xs_page, 'normal');
        my ($tr, $tg, $tb) = $font->hex_to_rgb('#fff');
        my $tw = $font->measure_text($text) * ($size / ($font->size || 9));
        my $tx = $x0 + ($w - $tw) / 2;
        $tx = $x0 + 4 if $tw > $w - 4;
        my $ty = $y0 + ($h - $size) / 2 + 1;
        $overlay_canvas->q
                       ->BT
                       ->rg($tr, $tg, $tb)
                       ->Tf($res, $size)
                       ->Tm(1, 0, 0, 1, $tx, $ty)
                       ->Tj($text)
                       ->ET
                       ->Q;
    }

    return $filtered . $overlay_canvas->to_bytes;
}

# ── Color Management ──────────────────────────────────────

sub set_color_space {
    my ($self, $type, %args) = @_;
    my $cs;
    if ($type eq 'sRGB') {
        $cs = PDF::Make::Color->srgb;
    } elsif ($type eq 'separation') {
        $cs = PDF::Make::Color->separation(
            $args{name}, $args{c} // 0, $args{m} // 0, $args{y} // 0, $args{k} // 0
        );
    } else {
        die "PDF::Make::Builder: unknown color space '$type'";
    }
    my $xs_doc = doc $self;
    $cs->write_to_doc($xs_doc);
    return $self;
}

# ── Tagged PDF / Accessibility ────────────────────────────

sub enable_tagging {
    my ($self) = @_;
    my $xs_doc = doc $self;
    my $tree = PDF::Make::Structure->create_tree($xs_doc);
    _struct_tree $self, $tree;
    _tagging $self, 1;
    return $self;
}

# ── Forms ─────────────────────────────────────────────────

my %_field_class = (
    text     => 'PDF::Make::Builder::Form::Field::Text',
    checkbox => 'PDF::Make::Builder::Form::Field::Checkbox',
    radio    => 'PDF::Make::Builder::Form::Field::Radio',
    combo    => 'PDF::Make::Builder::Form::Field::Combo',
    dropdown => 'PDF::Make::Builder::Form::Field::Combo',
    listbox  => 'PDF::Make::Builder::Form::Field::Listbox',
    list     => 'PDF::Make::Builder::Form::Field::Listbox',
    button   => 'PDF::Make::Builder::Form::Field::Button',
);

sub add_field {
    my ($self, %args) = @_;

    my $type = delete $args{type} // die "PDF::Make::Builder: add_field requires type";
    my $name = delete $args{name} // die "PDF::Make::Builder: add_field requires name";

    my $class = $_field_class{$type}
        // die "PDF::Make::Builder: unknown field type '$type'";

    # Default to structured mode. Enter raw mode for explicit coordinates
    # or when requested directly.
    my $raw_mode = delete $args{raw_mode};
    if (!defined $raw_mode) {
        $raw_mode = (exists $args{rect} || exists $args{x} || exists $args{y}) ? 1 : 0;
    }

    if (!$raw_mode) {
        if (exists $args{default} && !exists $args{default_value}) {
            $args{default_value} = delete $args{default};
        }
        my $field = $class->new(field_name => $name, %args);
        $field->add($self);
        return $self;
    }

    # Raw mode (direct widget placement)
    my $default = delete $args{default};
    $default = delete $args{default_value} unless defined $default;

    my $cur = page $self;
    die "PDF::Make::Builder: no current page" unless $cur;

    my ($x, $y, $w, $h);
    if ($args{rect}) {
        ($x, $y, $w, $h) = @{delete $args{rect}};
    } else {
        # Cursor-relative placement like add_text
        $x = delete $args{x} // $cur->content_x;
        $w = delete $args{w} // $cur->width;
        $h = delete $args{h} // 22;
        if (defined $args{y}) {
            $y = delete $args{y};
        } else {
            $y = $cur->cursor_y - $h;
        }
        # Advance cursor past the field
        $cur->advance_y($h + 4);
    }
    die "PDF::Make::Builder: field requires coordinates"
        unless defined $x && defined $y && defined $w && defined $h;

    my %fargs = (
        field_name    => $name,
        x             => $x,
        y             => $y,
        w             => $w,
        h             => $h,
        raw_mode      => 1,
    );

    $fargs{default_value} = $default if defined $default;

    $fargs{readonly} = $args{readonly} ? 1 : 0 if exists $args{readonly};
    $fargs{required} = $args{required} ? 1 : 0 if exists $args{required};
    $fargs{da} = $args{da} if exists $args{da};

    # Field-specific passthrough
    $fargs{options} = $args{options} if exists $args{options};
    $fargs{caption} = $args{caption} if exists $args{caption};
    $fargs{on_value} = $args{on_value} if exists $args{on_value};

    my $field = $class->new(%fargs);
    $field->add($self);

    return $self;
}

sub flatten_form {
    my ($self) = @_;
    _flatten_pending $self, 1;
    return $self;
}

# ── Digital Signatures ────────────────────────────────────

sub sign {
    my ($self, %args) = @_;
    _sign_args $self, \%args;
    return $self;
}

# ── TOC ────────────────────────────────────────────────────

sub add_toc {
    my ($self, %args) = @_;
    my $cfg = configure $self;
    my $toc_cfg = $cfg->{toc} // {};
    my $cur = page $self;
    my $default_toc_page = $cur ? ($cur->num - 1) : 0;
    %args = (%$toc_cfg, %args);
    $args{page_index} = $default_toc_page unless exists $args{page_index};
    toc $self, PDF::Make::Builder::TOC->new(%args);
    return $self;
}

# ── Save ───────────────────────────────────────────────────

sub save {
    my ($self) = @_;

    # Render TOC if present
    my $cur = page $self;
    if ($cur) {
        my $t = toc $self;
        if ($t && @{$t->entries}) {
            $t->render($self);
        }
    }

    # Render headers/footers onto each page's canvas, then finalize
    my $all_pages = pages $self;
    my $offset = page_offset $self;
    my $rewrite = _apply_redactions_pending $self;
    for my $bp (@$all_pages) {
        if ($bp->imported) {
            # Imported pages keep their original content, but any overlay
            # drawing issued against the Builder's canvas (e.g. a box
            # around extracted text) needs to be appended so it renders
            # on top of the source graphics.
            my $overlay = $bp->canvas->to_bytes;
            if (defined $overlay && length $overlay) {
                $bp->xs_page->append_content($overlay);
            }
            next;
        }
        my $hdr = $bp->header;
        my $ftr = $bp->footer;
        my $pnum = $bp->num + $offset;

        if ($hdr) {
            $hdr->render($self, $bp, $pnum);
        }
        if ($ftr) {
            $ftr->render($self, $bp, $pnum);
        }

        # Finalize page content; filter through the redaction rewriter
        # when the user has called apply_redactions.
        my $bytes = ($rewrite && @{$bp->redactions})
            ? $self->_rewrite_redacted_canvas_bytes($bp)
            : $bp->canvas->to_bytes;
        $bp->xs_page->set_content($bytes);
    }

    if (_sanitize_pending $self) {
        PDF::Make::Redaction->sanitize(doc $self);
    }

    # Apply deferred watermarks after all page content is set
    {
        my $wms = _watermarks $self;
        if ($wms && @$wms) {
            my $xs_doc = doc $self;
            for my $wm (@$wms) {
                $xs_doc->add_watermark($wm);
            }
        }
    }

    # Flatten form fields if requested (after set_content so canvas is committed)
    if (_flatten_pending $self) {
        my $xs_doc = doc $self;
        my $form = eval { PDF::Make::FormPtr::get($xs_doc) };
        $form->flatten if $form;
    }

    # Finalize form if any fields were added
    {
        my $xs_doc = doc $self;
        my $form = eval { PDF::Make::FormPtr::get($xs_doc) };
        if ($form) {
            PDF::Make::FormPtr::finalize($form);
        }
    }

    # Apply encryption if configured.  The actual /Encrypt dict is built,
    # and per-object encryption applied, inside pdfmake_doc_write.
    my $enc = _encrypt_args $self;
    if ($enc) {
        my $algo  = $enc->{algorithm}      // 'AES-256';
        my $user  = $enc->{user_password}  // $enc->{password} // '';
        my $owner = $enc->{owner_password} // $user;
        my $perms = $enc->{permissions}    // 0xFFFFFFFC;
        my $xs_doc = doc $self;
        $xs_doc->set_encryption($algo, $user, $owner, $perms);
    }

    # Apply digital signature if configured.  pdfmake_doc_sign returns
    # the signed PDF bytes (original doc + /Sig dict + PKCS#7 /Contents),
    # so when signing is active we write the returned bytes, not the
    # unsigned doc->to_bytes() output.
    my $sig = _sign_args $self;
    my $signed_bytes;
    if ($sig && $sig->{pkcs12} && -f $sig->{pkcs12}) {
        my $identity = PDF::Make::Signature->load_identity(
            file     => $sig->{pkcs12},
            password => $sig->{password} // '',
        );
        die "PDF::Make::Builder: sign: identity has no usable signing key"
            unless $identity && $identity->can_sign;

        my $xs_doc = doc $self;
        $signed_bytes = PDF::Make::Signature::_sign_document($xs_doc,
            identity      => $identity,
            reason        => $sig->{reason},
            location      => $sig->{location},
            contact       => $sig->{contact},
            name          => $sig->{name},
            hash          => $sig->{hash},
            timestamp_url => $sig->{timestamp_url},
            tsa_timeout   => $sig->{tsa_timeout},
            visible       => $sig->{visible},
            page          => $sig->{page},
            rect          => $sig->{rect},
            appearance    => $sig->{appearance},
        );
    }

    # Write to file
    my $xs_doc = doc $self;
    my $fname = file_name $self;
    $fname .= '.pdf' unless $fname =~ /\.pdf$/i;
    my $dir = dirname($fname);
    if (defined $dir && length $dir && $dir ne '.') {
        make_path($dir) unless -d $dir;
    }
    if (defined $signed_bytes) {
        open my $fh, '>:raw', $fname or die "PDF::Make::Builder: cannot write '$fname': $!";
        print $fh $signed_bytes;
        close $fh;
    } else {
        $xs_doc->to_file($fname);
    }

    return $self;
}

# ── Onsave callback management ─────────────────────────────

sub onsave {
    my ($self, $key, $method, %args) = @_;
    my $cbs = onsave_cbs $self;
    push @$cbs, [$key, $method, %args];
    onsave_cbs $self, $cbs;
    return $self;
}

# ── Text extraction (phase 13) ────────────────────────────

sub extract_text {
    my ($self, $file, $page_index) = @_;
    $page_index //= 0;
    my $parser = PDF::Make::Parser->from_file($file);
    return PDF::Make::Extract->extract($parser, $page_index);
}

sub extract_structured {
    my ($self, $file, %args) = @_;
    my $page_index = $args{page} // 0;
    my $include_invisible = exists $args{invisible}
                          ? ($args{invisible} ? 1 : 0)
                          : 1;
    my $parser = PDF::Make::Parser->from_file($file, repair => 1);
    $parser->parse;
    my $reader = PDF::Make::Reader->new($parser);
    if ($reader->is_encrypted && !$reader->is_authenticated) {
        my $pw = $args{password} // '';
        my $rc = $reader->set_password($pw);
        die "PDF::Make::Builder: extract_structured: authentication failed for '$file'"
            if $rc < 0;
    }
    my $raw = PDF::Make::Extract->_extract_structured(
        $reader, $page_index, $include_invisible);
    return PDF::Make::Extract::Result->new(data => $raw);
}

sub extract_annotations {
    my ($self, $file, %args) = @_;
    my $parser = PDF::Make::Parser->from_file($file, repair => 1);
    $parser->parse;
    my $reader = PDF::Make::Reader->new($parser);
    if ($reader->is_encrypted && !$reader->is_authenticated) {
        my $pw = $args{password} // '';
        my $rc = $reader->set_password($pw);
        die "PDF::Make::Builder: extract_annotations: authentication failed for '$file'"
            if $rc < 0;
    }
    my $list = PDF::Make::Extract->_extract_annotations($reader);
    return wantarray ? @$list : $list;
}

sub detect_tables {
    my ($self, $file, %args) = @_;
    my $page_index = $args{page} // 0;
    my $parser = PDF::Make::Parser->from_file($file, repair => 1);
    $parser->parse;
    my $reader = PDF::Make::Reader->new($parser);
    if ($reader->is_encrypted && !$reader->is_authenticated) {
        my $pw = $args{password} // '';
        my $rc = $reader->set_password($pw);
        die "PDF::Make::Builder: detect_tables: authentication failed for '$file'"
            if $rc < 0;
    }
    my $list = PDF::Make::Extract->_detect_tables($reader, $page_index);
    return wantarray ? @$list : $list;
}

# ── Open existing PDF ────────────────────────────────────

sub open_existing {
    my ($class, $file, %args) = @_;

    my $password = delete $args{password};
    my $out_file = delete $args{file_name} // $file;

    die "PDF::Make::Builder: open_existing: file '$file' not found" unless -f $file;

    my $self = $class->new(file_name => $out_file, %args);

    # Round-trip the source document: content + resources + dimensions.
    $self->append_pdf($file, password => $password);

    return $self;
}

# ── Append pages from another PDF ─────────────────────────

sub append_pdf {
    my ($self, $file, %args) = @_;

    die "PDF::Make::Builder: append_pdf: file '$file' not found" unless -f $file;

    my $parser = PDF::Make::Parser->from_file($file, repair => 1);
    $parser->parse;
    my $reader = PDF::Make::Reader->new($parser);

    if ($reader->is_encrypted && !$reader->is_authenticated) {
        my $pw = $args{password} // '';
        my $rc = $reader->set_password($pw);
        die "PDF::Make::Builder: append_pdf: authentication failed for '$file'"
            if $rc < 0;
    }

    my $xs_doc = doc $self;
    my $importer = PDF::Make::Import->new($reader, $xs_doc);

    my $count = $reader->page_count;
    my @indices = $args{pages} ? @{$args{pages}} : (0 .. $count - 1);

    for my $idx (@indices) {
        die "PDF::Make::Builder: append_pdf: page index $idx out of range (file has $count pages)"
            unless $idx >= 0 && $idx < $count;

        my $before = $xs_doc->page_count;
        my $ok = $importer->import_page($idx);
        unless ($ok) {
            warn "PDF::Make::Builder: append_pdf: failed to import page $idx from '$file'";
            next;
        }
        my $after = $xs_doc->page_count;

        for my $pi ($before .. $after - 1) {
            my $xs_page = $xs_doc->get_page($pi);
            my $pages   = pages $self;
            my $num     = scalar(@$pages) + 1;
            my $bp = PDF::Make::Builder::Page->new(
                page_size  => 'custom',
                background => '#fff',
                columns    => 1,
                padding    => 20,
                num        => $num,
                w          => $xs_page->width,
                h          => $xs_page->height,
                canvas     => PDF::Make::Canvas->new,
                xs_page    => $xs_page,
                imported   => 1,
            );
            push @$pages, $bp;
            pages $self, $pages;
            page $self, $bp;
        }
    }

    return $self;
}

sub merge {
    my ($class, $out_file, @inputs) = @_;
    die "PDF::Make::Builder::merge: no input files" unless @inputs;

    my $b = $class->new(file_name => $out_file);
    for my $f (@inputs) {
        $b->append_pdf($f);
    }
    $b->save;
    return $b;
}

# ── Page editing (phase 15) ───────────────────────────────

sub remove_page {
    my ($self, $index) = @_;
    my $ps = pages $self;
    die "PDF::Make::Builder: page index out of range" unless $index >= 0 && $index < scalar @$ps;
    splice @$ps, $index, 1;
    # Re-number remaining pages
    for my $i (0 .. $#$ps) {
        $ps->[$i]->num($i + 1);
    }
    pages $self, $ps;
    # Switch to last page if current was removed
    if (scalar @$ps) {
        page $self, $ps->[-1];
    } else {
        page $self, undef;
    }
    return $self;
}

sub move_page {
    my ($self, $from, $to) = @_;
    my $ps = pages $self;
    die "PDF::Make::Builder: from index out of range" unless $from >= 0 && $from < scalar @$ps;
    die "PDF::Make::Builder: to index out of range" unless $to >= 0 && $to < scalar @$ps;
    my $pg = splice @$ps, $from, 1;
    splice @$ps, $to, 0, $pg;
    for my $i (0 .. $#$ps) {
        $ps->[$i]->num($i + 1);
    }
    pages $self, $ps;
    return $self;
}

sub duplicate_page {
    my ($self, $index) = @_;
    my $ps = pages $self;
    die "PDF::Make::Builder: page index out of range" unless $index >= 0 && $index < scalar @$ps;

    my $src = $ps->[$index];

    # Finalize source page content
    $src->xs_page->set_content($src->canvas->to_bytes);

    # Create a new page with same dimensions
    my $xs_doc = doc $self;
    my $xs_page = $xs_doc->add_page($src->w, $src->h);
    my $canvas = PDF::Make::Canvas->new;

    my $bp = PDF::Make::Builder::Page->new(
        page_size  => $src->page_size,
        background => $src->background,
        columns    => $src->columns,
        padding    => $src->padding,
        num        => scalar(@$ps) + 1,
        w          => $src->w,
        h          => $src->h,
        canvas     => $canvas,
        xs_page    => $xs_page,
        header     => $src->header,
        footer     => $src->footer,
    );

    push @$ps, $bp;
    pages $self, $ps;
    page $self, $bp;

    return $self;
}

sub rotate_page {
    my ($self, $index, $degrees) = @_;
    my $ps = pages $self;
    die "PDF::Make::Builder: page index out of range" unless $index >= 0 && $index < scalar @$ps;
    die "PDF::Make::Builder: rotation must be 0, 90, 180, or 270"
        unless grep { $degrees == $_ } (0, 90, 180, 270);

    # Swap width/height for 90/270 rotation
    my $pg = $ps->[$index];
    if ($degrees == 90 || $degrees == 270) {
        my ($w, $h) = ($pg->w, $pg->h);
        $pg->w($h);
        $pg->h($w);
    }

    return $self;
}

# ── Load TrueType font (phase 12) ────────────────────────

sub load_ttf {
    my ($self, $path, %args) = @_;
    my $font_obj = PDF::Make::Font->from_file($path);
    my $doc = doc $self;
    my $obj_num = $font_obj->write_to_doc($doc);

    my $name = $args{name} // 'TT' . $obj_num;
    my $cur = page $self;
    if ($cur) {
        $cur->xs_page->add_font($name, $font_obj->base_font);
    }

    return $self;
}

1;

__END__